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Preface 



I ntroduction 



1: The pattern 
concept 

This book introduces the important and yet non- 
traditional "patterns" approach to program design. 

Probably the most important step forward in object-oriented design isthe 
"design patterns" movement, chronicled in Design Patterns, by Gamma, 
H el m, J oh nson & V I i ssi d es (A d d i son-WesI ey, 1995) FThat book shows 23 
different solutions to particular classes of problems. I n this book, the 
basic concepts of design patterns will beintroduced along with examples. 
This should whet your appetite to read Design Patterns by Gamma, et. al., 
a source of what has now become an essential, almost mandatory, 
vocabulary for OOP programmers. 

Thelatter part of this book contains an example of the design evolution 
process, starting with an initial solution and moving through the logic 
and process of evol vi ng the sol uti on to more appropri ate desi gns. The 
program shown (a trash sorting simulation) has evolved over time, and 
you can look at that evolution as a prototype for the way your own 
design can start as an adequate sol uti on to a particular problem and 
evol ve i nto a f I exi bl e approach to a cl ass of probl ems. 

What is a pattern? 

Initially, you can think of a pattern as an especially clever and insightful 
way of solving a particular class of problems. That is, it looks like a lot of 
people have worked out all the angles of a problem and havecomeup 
with the most general , f I exi bl e sol uti on for it. The probl em coul d be one 



1 But bewarned: the examples are in C++. 



you haveseen and solved before, but your solution probably didn't have 
the kind of completeness you'll see embodied in a pattern. 

Although they're called "design patterns," they really aren't tied to the 
realm of design. A pattern seems to stand apart from the traditional way 
of thinking about analysis, design, and implementation. Instead, a 
pattern embodies a complete idea within a program, and thus it can 
sometimes appear at the analysisphase or high-level design phase. This 
is interesting because a pattern has a direct implementation in code and 
so you might not expect it to show up before low -level design or 
implementation (and in fact you might not realize that you need a 
particular pattern until you get to those phases). 

The basi c concept of a pattern can al so be seen as the basi c concept of 
program design: adding a layer of abstraction. Whenever you abstract 
something you 're isolating particular details, and one of the most 
compel ling moti vati ons behi nd thi s i s to separate th i n gs that chan ge from 
things that stay the same. Another way to put this is that once you find 
some part of your program that's likely to change for one reason or 
another, you'll want to keep those changes from propagating other 
changes throughout your code. N ot only does this make the code much 
cheaper to maintain, but it also turns out that it is usually simpler to 
understand (which results in lowered costs). 

Often, the most difficult part of developing an elegant and cheap-to- 
mai ntain design is in discovering what I call "the vector of change." 
(Here, "vector" refers to the maximum gradient and not a container 
cl ass.) This means f i ndi ng the most i mportant thi ng that changes i n your 
system, or put another way, discovering where your greatest cost is. 
Once you discover the vector of change, you havethefocal point around 
which to structure your design. 

So the goal of design patterns is to isolate changes in your code. If you 
look at it this way, you've been seeing some design patterns already in 
this book. For example, inheritance can bethought of as a design pattern 
(al beit one i mpl emented by the compi I er). 1 1 al I ows you to express 
differences in behavior (that's the thing that changes) in objects that all 
have the same interface (that's what stays the same). Composition can 
also be considered a pattern, si nee it allows you to change— dynamically 
or statically— the objects that implement your class, and thustheway 
that class works. 



You'vealso already seen another pattern that appears i n Design Patterns: 
theiterator (Java 1.0 and 1.1 capriciously calls it the Enumeration; Java 2 
containers use "iterator"). This hides the particular implementation of the 
contai n er as y ou ' re step pingthroughandselectingtheel ements on e by 
one. The iterator al lows you to write generic code that performs an 
operation on all of the el ements in a sequence without regard to the way 
that sequence is built. Thus your generic code can be used with any 
container that can produce an iterator. 



One of the events that's occurred with the rise of design patterns is what 
could be thought of as the "pollution" of theterm- people have begun to 
use the term to mean just about anything synonymous with "good." 
After some pondering, I've come up with a sort of hierarchy describing a 
succession of different types of categories: 

1. Idiom: how wewritecodein a particular language to do this 
parti cular type of thing. Thiscould be something as common as 
the way that you code the process of steppi ng through an array i n 
C (and not running off the end). 

2. Specific Design: the solution thatwecameup with tosolvethis 
particular problem. This might bea clever design, but it makes no 
attempt to be general . 

3. Standard Design: a way to solve this kind of problem. A design 
that has become more general, typically through reuse. 

4. Design Pattern: how to solve an entire class of similar problem. 
This usually only appears after applying a standard design a 
number of times, and then seeing a common pattern throughout 
these applications. 

I feel this helps put things in perspective, and to show where something 
might fit. H owever, it doesn't say that one is better than another. It 
doesn't make sense to try to take every problem solution and generalize it 
to a design pattern - it's not a good use of your ti me, and you can't force 
the discovery of patterns that way; they tend to be subtl e and appear over 
time. 



Pattern 




One could also argue for the inclusion of Analysis Pattern and 
Architectural Pattern in this taxonomy. 



Possibly the simplest design pattern isthe singleton, which is a way to 
provide one and only one object of a particular type. This is used in the 
J ava I i brari es, but here's a more d i rect exampl e: 

//: cOl : SingletonPattern . java 

// The Singleton design pattern: you can 

// never instantiate more than one. 

// Since this isn't inherited from a Cloneable 
// base class and cloneability isn't added, 
// making it final prevents cloneability from 
// being added through inheritance: 
final class Singleton { 

private static Singleton s = new Singleton ( 47 ) ; 

private int i; 

private Singleton ( int x) { i = x; } 
public static Singleton getRef erence ( ) { 
return s; 

} 

public int getValue ( ) { return i; } 
public void setValue (int x) { i = x; } 



public class SingletonPattern { 

public static void main ( String [ ] args) { 
Singleton s = Singleton . getRef erence () ; 
System. out .println (s . getValue ( ) ) ; 
Singleton s2 = Singleton . getRef erence () ; 
s2 . setValue (9) ; 

System. out .println (s . getValue ( ) ) ; 
try { 

// Can't do this: compile-time error. 
// Singleton s3 = (Singleton) s2 . clone () ; 
} catch (Exception e) { 

e . printStackTrace ( System. err ) ; 

} 



The 




} ///:- 



The key to creating a singleton is to prevent the client programmer from 
havi ng any way to create an object except the ways you provide. You 
must make al I constructors private, and you must create at least one 
constructor to prevent the compiler from synthesizing a default 
constructor for you (which it will create as "friendly"). 

At this point, you decide how you're going to create your object. Here, 
it's created statically, but you can also wait until the client programmer 
asks for one and create it on demand. In any case, the object should be 
stored privately. You provide access through public methods. Here, 
getReference( ) produces the reference to theSingleton object. The rest 
of the interface (getValue( ) and setValueO) isthe regular class interface. 

Java also allows the creation of objects through cloning. In this example, 
making the class final prevents cloning. Si nee Singleton isinherited 
directly from Object, theclone( ) method remains protected so it cannot 
be used (doing so produces a compile-ti me error). However, if you're 
inheriting from a class hierarchy that has already overridden clone( ) as 
public and implemented Cloneable, the way to prevent cloning isto 
override clone( ) and throw aCloneNotSupportedException as 
described in Appendix A. (You could alsooverrideclone( ) and simply 
return this, butthatwould bedeceiving since the client programmer 
would think they were cloning the object, butwould instead still be 
dealing with the original.) 

N ote that you aren't restri cted to creati ng onl y one object. Thi s i s al so a 
technique to create a limited pool of objects. In that situation, however, 
you can be confronted with the problem of sharing objects in the pool. If 
this is an issue, you can create a solution involving a check-out and 
check-in of the shared objects. 

Classifying patterns 

The Design Patterns book discusses 23 different patterns, classified under 
three purposes (all of which revolve around the particular aspect that can 
vary). The three purposes are: 



1. Creational: how an object can be created. This often involves 
isolating the details of object creation so your code isn't dependent 
on what types of objects there are and thus doesn't have to be 
changed when you add a new type of object. The aforementioned 
Singleton is classified as a creational pattern, and later in this book 
you'll see examples of Factory M ethod and Prototype. 

2. Structural: designing objects to satisfy particular project 
constraints. These work with the way objects are connected with 
other objects to ensure that changes in the system don't require 
changes to those connections. 

3. Behavioral: objectsthat handleparticular typesof actions within a 
program. These encapsul ate processes that you want to perform, 
such as interpreting a language, fulfilling a request, moving 
through a sequence (as in an iterator), or implementing an 
algorithm. Thisbook contains examples of theObserver and the 
Visitor patterns. 

The Design Patterns book has a section on each of its 23 patterns along 
w i th one or more exampl es for each, typi cal I y i n C ++ but someti mes i n 
Smalltalk. (You'll find that this doesn't matter too much si nee you can 
easily translate the concepts from either language into Java.) This book 
will not repeat all the patterns shown in Design Patterns si nee that book 
stands on its own and should be studied separately. Instead, this book 
will give some examples that should provideyou with a decent feel for 
what patterns are about and why they are so important. 

After years of looking at these things, it began to occur to me that the 
patterns themselves use basic principles of organization, other than (and 
more fundamental than) those described in Design Patterns. These 
principles are based on the structure of the implementations, which is 
where I have seen great similarities between patterns (more than those 
expressed in Design Patterns). Although wegenerally try to avoid 
implementation in favor of interface, I have found that it's often easier to 
think about, and especially to learn about, the patterns in terms of these 
structural principles. Thisbook will attempt to present the patterns based 
on their structure in stead of the categories presented in Design Patterns. 



The development 
challenge 

Issues of development, theUML process, Extreme Programming. 

Is evaluation valuable? The Capability Immaturity Model: 

Wiki P age: http:/ / c2.com/ cgi-bin/ wiki?CapabilitylmMaturityModel 
Article: Fttp:/ / www.embedded.com/ 98/ 9807br.html 

Pair programming research: 

http:/ / collaboration.csc.ncsu.edu/ laurie/ 

Exercises 

1 . Singleton Pattern Java always creates an object, even if it's never 
used. Modify this program to use lazy initialization, so the 
singleton object is only created the first time that it is needed. 

2 . UsingSingl eton Pattern .j ava as a starti ng poi nt, create a cl ass that 
manages a fixed number of its own objects. Assume the objects 
are database connections and you only have a license to use a 
fixed quantity of these at any onetime. 



2: Unit Testing 



One of the important recent realizations is the dramatic 
value of unit testing. 

This is the process of bui Idi ng i integrated tests i nto al I the code that you 
create, and running those tests every time you do a build. It's as if you 
are extendi ng the compi I er, tel I i ng it more about w hat your program is 
supposed to do. That way, the build process can check for more than just 
syntax errors, si nee you teach it how to check for semanti c errors as wel I . 

C-style programming languages, and C-H-in particular, havetypically 
valued performance over programming safety. The reason that 
developing programs in Java isso much faster than in C++(roughly 
twice as fast, by most accounts) is because of Java's safety net: features 
I ike better type checking, enforced exceptions and garbage col lection. By 
integrating unittesting into your build process, you are extending this 
safety net, and the result is that you can develop faster. You can also be 
bol der i n the changes that you make, and more easi ly ref actor your code 
when you discover design or implementation flaws, and in general 
produce a better product, faster. 

Unittesting is not generally considered a design pattern; in fact, it might 
be considered a "development pattern," but perhaps there are enough 
"pattern" phrases in the world already. Its effect on development isso 
significant that it will be used throughout this book, and thuswill be 
introduced here. 

My own experience with unittesting began when I realized that every 
program in a book must be automatically extracted and organized into a 
source tree, along with appropriate makefiles (or some equivalent 
technology) so that you could just type make to build the whole tree. The 
effect of this process on the code quality of the book was so immediate 
and dramatic that it soon became (in my mind) a requisite for any 
programming book— how can you trust code that you didn't compile? I 
also discovered that if I wanted to makesweeping changes, I could do so 
using search-and-repl ace throughout the book, and also bashing the code 



around at will. I knew that if I introduced a flaw, the code extractor and 
the makefiles would flush it out. 

As programs became more complex, however, I also found that there was 
a serious hole in my system. Being ableto successfully compile programs 
is clearly an important first step, and for a published book it seemed a 
fairly revolutionary one— usually due to the pressures of publishing, it's 
quite typical to randomly open a programming book and discover a 
coding flaw. H owever, I kept getting messages from readers reporting 
semantic problems in my code (in Thinking in Java). These problems could 
only bediscovered by running the code. Naturally, I understood thisand 
had taken some early falteri ng steps towards i mplementi ng a system that 
would perform automatic execution tests, but I had succumbed to the 
pressures of publishing, all the while knowing that there was definitely 
something wrong with my process and that it would come back to bite 
me in the form of embarrassing bug reports (in the open source world, 
embarrassment is one of the pri me moti vati ng factors towards i ncreasi ng 
the quality of one's code!). 

The other problem was that I was lacking a structure for the testing 
system. Eventually, I started hearing about unit testing and J Unit 1 ! which 
provided a basis for a testing structure. However, even though J Unit is 
i ntended to make the creati on of test code easy, I wanted to see if I coul d 
makeiteven easier, applying the Extreme Programming principle of "do 
the si mpl est thi ng that coul d possi bly work" as a starti ng poi nt, and then 
evolving the system as usage demands (In addition, I wanted to try to 
reduce the amount of test code, in an attempt to fit more functionality in 
less code for screen presentations). This chapter is the result. 



As I mentioned, one of the problems that I encountered— that most 
people encounter, it turns out— was submitti ng to the pressures of 
pu bl i sh i ng and as a resu 1 1 1 etti ng tests f al I by the w aysi d e. Th i s i s easy to 
do if you forge ahead and write your program code because there's a 
little voice that tells you that, after all, you've got it working now, and 



1 http:/ / www.junit.org 



Write 




would n't it be more interesting/ useful/ expedient to just go on and write 
that other part (wecan always go back and write the tests later). As a 
result, the tests take on less importance, as they often do in a 
development project. 

The answer to this problem, which I first found described in Extreme 
Programming Explained, is to w rite the tests before you write the code. This 
may seem to artif i ci al I y force testi ng to the forefront of the devel opment 
process, but what it actually does is to give testing enough additional 
value to make it essential. If you write the tests first, you: 

1. Describe what the code is supposed to do, not with some external 
graphical tool but with code that actually I ays the specification 
down in concrete, verifiable terms. 

2. Providean exampleof how thecodeshould be used; again, this is 
a working, tested example, normally showing all the important 
method calls, rather than just an academic description of a library. 

3. Provide a way to verify when the code is finished (when all the 
tests run correctly). 

Thus, if you write the tests first then testing becomes a development tool, 
not just a verification step that can be skipped if you happen to feel 
comfortable about the codethat you just wrote (a comfort, I have found, 
that is usually wrong). 

You can find convincing arguments in Extreme Programming Explained, as 
"write tests first" is a fundamental principle of XP. If you aren't 
convinced you need to adopt any of the changes suggested by XP, note 
that according to Software Engineering I nstitute(SEI) studies, nearly 70% 
of software organi zati ons are stuck i n the f i rst two I evels of SEI 's seal e of 
sophistication: chaos, and slightly better than chaos. If you change 
nothing else, add automated testing. 

A very simple framework 

As mentioned, a primary goal of this code is to make the writing of unit 
testing code very simple, even simpler than with J Unit. As further needs 
arediscovered during the use of this system, then that functionality can be 



ad d ed , but to start w i th th e f ramew or k w i 1 1 j u st provi d e a w ay to easi I y 
create and run tests, and report failure if something breaks (success will 
produce no results other than normal output that may occur during the 
running of the test). My intended use of this framework is in makefiles, 
and make aborts if there is a non-zero return value from the execution of 
a command. The build process will consist of compilation of the 
programs and execution of unittests, and if make gets all the way 
through successfully then the system will be validated, otherwiseitwill 
abort at the pi ace of f ai I ure. The error messages will report the test that 
failed but not much else, so that you can provide whatever granularity 
that you need by writi ng as many tests as you want, each one coveri ng as 
much or as little as you f i nd necessary. 

In some sense, thisframework provides an alternative pi ace for all those 
"print" statements I've written and later erased over the years. 

To create a set of tests, you start by maki ng a stati c i nner cl ass i nsi de the 
class you wish to test (your test code may also test other cl asses; it's up to 
you).Thistestcodeisdistinguished by inheriting from UnitTest: 

// : com: bruceeckel : test : UnitTest . java 
// The basic unit testing class 
package com. bruceeckel . test; 
import java . util . ArrayList ; 

public class UnitTest { 
static String testID; 

static ArrayList errors = new ArrayList (); 
// Override cleanup () if test object 
// creation allocates non-memory 
// resources that must be cleaned up: 
protected void cleanup () {} 
// Verify the truth of a condition: 
protected final void assert (boolean condition) { 
if ( ! condition) 

errors .add ("failed: " + testID); 

} 

} ///:- 



The only testing method [[ So far ]] isassert( ), which is protected so that 
it can be used from the inheriting class. All this method does is verify 
that something istrue. If not, it adds an error to the list, reporting that the 



current test (established by the static testID, which is set by the test- 
running program that you shall see shortly) has failed. Although this is 
not a lot of information— you might also wish to havethe line number, 
which could be extracted from an exception— it may be enough for most 
situations. 

UnlikeJUnit (which usessetUp( ) and tearDown( ) methods), test objects 
will be built using ordinaryjava construction. You define the test objects 
by creating them as ordinary class members of the test class, and a new 
test cl ass object will be created for each test method (thus preventi ng any 
problems that might occur from side effects between tests). Occasionally, 
the creation of a test object will allocate non-memory resources, in which 
case you must override cleanup( ) to release those resources. 

Writing tests 

Writi ng tests becomes very si mpl e. H ere's an exampl e that creates the 
necessary static inner class and performs trivial tests: 

//: c02 : TestDemo . java 

// Creating a test 

import com . bruceeckel . test .* ; 

public class TestDemo { 

private static int objCounter = 0; 
private int id = ++ob jCounter; 
public TestDemo ( String s) { 

System. out .println (s + ": count = " + id); 

} 

public void close () { 

System. out .println ( "Cleaning up: " + id); 

} 

public boolean someCondition ( ) { return true; } 
public static class Test extends UnitTest { 
TestDemo testl = new TestDemo ( "testl ") ; 
TestDemo test2 = new TestDemo ( "test2 ") ; 
public void cleanup () { 
test 2 . close ( ) ; 
testl . close ( ) ; 

} 

public void testA() { 

System. out .println ( "TestDemo . testA" ) ; 



assert (testl . someCondition ( ) ) ; 

} 

public void testB() { 

System. out .print In ( "TestDemo . testB" ) ; 
assert (test2 . someCondition ( ) ) ; 
assert (TestDemo . objCounter != ) ; 

} 

// Causes the build to halt: 

//! public void test3() { assert ( false) ; } 

} 

} ///:- 

Thetest3( ) method iscommented out because, as you'll see, it causes the 
automati c bu i I d of th i s book's sou rce-cod e tree to stop . 

You can name your inner class anything you'd like; the only important 
factor isthat it extends UnitT est. You can also include any necessary 
support code in other methods. Only public methods that take no 
arguments and return void wi 1 1 be treated as tests (the names of these 
methods are also not constrained). 

The above test class creates two i nstances of TestD emo. TheTestD emo 
constructor prints something, so that we can see it being called. You 
could also define a default constructor (the only kind that is used by the 
test framework), although none is necessary here. The TestD emo class 
has a close( ) method which suggests it is used as part of object cleanup, 
so this is called in the overridden cleanup( ) method inTest. 

Thetesting methods usetheassert( ) method to validate expressions, and 
if there i s a f ai I ure the i nf ormati on i s stored and pri nted after al I the tests 
are run. Of course, the assert( ) arguments are usual ly more compl i cated 
than this; you'll see more examples throughout the rest of this book. 

Notice that in testB( ), the private field objCounter is accessible to the 
testing code— this is because Test has the permissions of an inner class. 

You can see that writing test code requires very little extra effort, and no 
knowledge other than that used for writing ordinary classes. 

To run the tests, you useRunUnitTests.java (which will beintroduced 
shortly). The command for the above code looks I i ke this: 

javacom.bru ceeck el .test. R u n U n i tT ests T est D em o 



It produces the foil owing output: 



testl: count = 1 
test2: count = 2 
Test Demo . test A 
Cleaning up: 2 
Cleaning up: 1 
testl: count = 3 
test2: count = 4 
TestDemo . testB 
Cleaning up: 4 
Cleaning up: 3 

A 1 1 the output i s noise as far as the success or fai I u re of the unit testi ng is 
concerned. Only if one or more of the unit tests fai I does the program 
returns a non-zero val ue to termi nate the make process after the error 
messages are produced. Thus, you can choose to produce output or not, 
as it suits your needs, and the test class becomes a good place to put any 
printing codeyou might need— if you do this, you tend to keep such code 
around rather than putting it in and stripping it out as is typically done 
with tracing code. 

If you need to add a test to a class derived from one that already has a 
test class, it's no problem, as you can see here: 

//: c02 : TestDemo2 . java 

// Inheriting from a class that 

// already has a test is no problem. 

import com . bruceeckel . test .* ; 

public class TestDemo2 extends TestDemo { 
public TestDemo2 (String s) { super (s); } 
// You can even use the same name 
// as the test class in the base class: 
public static class Test extends UnitTest { 
public void testA() { 

System. out .println ("TestDemo2 .testA") ; 
assert (1 + 1 == 2) ; 

} 

public void testB () { 

System . out . println ( "TestDemo2 .testB" ) ; 
assert (2 * 2 == 4) ; 

} 



} 

} ///:- 



Even the name of the inner class can be the same. In the above code, all 
the asserti ons are al ways true so the tests will never f ai I . 

White- box & black- box 
tests 

Th e u n i t test exampl es so far are w h at are trad itionally called white-box 
tests. This means that the test code has complete access to the internals of 
the cl ass that's bei ng tested (so it mi ght be more appropri ately cal I ed 
"transparent box" testing). White-box testing happens automatically 
when you makethe unit test class as an inner class of the class being 
tested , si nee i nner cl asses automati cal I y have access to all thei r outer cl ass 
elements, even those that are private. 

A possibly more common form of testing isblack-box testing, which refers 
to treating the class under test as an impenetrable box. You can't seethe 
internals; you can only access the public portions of the class. Thus, 
bl ack-box testi ng corresponds more cl osel y to f uncti onal testi ng, to verify 
the methods that the client programmer is going to use. In addition, 
bl ack-box testi ng provi des a mi ni mal i nstructi on sheet to the cl i ent 
programmer - in the absence of all other documentation, the black-box 
tests at I east demonstrate how to make basi c cal I s to the public cl ass 
methods. 

To perform bl ack-box tests usi ng the unit-testi ng framework presented i n 
thisbook, all you need to do is create your test class as a global class 
instead of an inner class. All the other rules are the same (for example, 
the unit test class must be public, and derived from UnitT est). 

There's one other caveat, which will also provide a little review of Java 
packages. If you want to be completely rigorous, you must put your 
bl ack-box test cl ass i n a separate d i rectory than the cl ass i t tests, 
otherwi se it wi 1 1 have package access to the el ements of the cl ass bei ng 
tested. That is, you'll beableto access protected and friendly elements of 
the cl ass bei ng tested . H ere's an exampl e: 



//: c02 : Testable . java 



public class Testable { 
private void fl() {} 

void f 2 ( ) {} // "Friendly": package access 
protected void f3() {} // Also package access 
public void f4 () { } 
} ///:~ 

Normally, the only method that should bedirectly accessible to the client 
programmer is f4( ). However, if you put your black- box test in the same 
directory, it automatically becomes part of the same package (in this case, 
the default package si nee none is specified) and then has inappropriate 
access: 

//: c02 : TooMuchAccess . java 
import com . bruceeckel . test .* ; 

public class TooMuchAccess extends UnitTest { 
Testable tst = new Testable (); 
public void testl() { 

tst.f2 () ; // Oops! 

tst.f3 () ; // Oops! 

tst. f4 () ; // OK 

} 

} 

You can solve the problem by moving TooM uchAccess.java into its own 
subdirectory, thereby putting it in its own default package (thus a 
different package from Testable.java). Of course, when you do this, then 
Testable must be in its own package, so that it can be imported (note that 
it is also possible to import a "package-less" class by giving the class 
name i n the i m port statement and ensuri ng that the cl ass is i n your 
CLASSPATH): 

//: c02 : testable : Testable . java 
package c02 . testable; 

public class Testable { 
private void fl() {} 

void f2() {} // "Friendly": package access 
protected void f3() {} // Also package access 
public void f4() {} 
} ///:- 



Here's the black-box test in its own package, showing how only public 
methods may be cal I ed : 

//: c02 : test : BlackBoxTest . java 
import c02 . testable . * ; 
import com . bruceeckel . test .* ; 

public class BlackBoxTest extends UnitTest { 
Testable tst = new Testable (); 
public void testl() { 

// ! tst. f2 () ; // Nope! 

// ! tst. f3 () ; // Nope! 

tst.f4(); // Only public methods available 

} 

} III:- 

N otethat the above program is indeed very similar to the onethat the 
client programmer would write to use your class, including the imports 
and available methods. So it does make a good programming example. 
Of course, it's easier from a coding standpoint to just make an inner class, 
and unless you're ardent about the need for specific black-box testing 
you may just want to go ahead and use the inner classes (with the 
knowledge that if you need to you can later extract the inner classes into 
separate black-box test classes, without too much effort). 

Running tests 

The program that runs the tests makes significant use of reflection so that 
w ri ti ng the tests can be si mpl e for the cl i ent programmer. 

// : com: bruceeckel : test : RunUnit Tests . java 

// Discovering the unit test 

// class and running each test. 

package com. bruceeckel . test; 

import java . lang . reflect .* ; 

import java . util . Iterator; 

public class RunUnitTests { 
public static void 

require (boolean requirement, String errmsg) { 
if (! requirement ) { 

System . err . println (errmsg) ; 
System . exit ( 1 ) ; 



} 

} 

public static void main ( String [ ] args) { 
require (args . length == 1, 

"Usage: RunUnitTests qualified-class"); 
try { 

Class c = Class . forName (args [ ]) ; 

// Only finds the inner classes 

// declared in the current class: 

Class [] classes = c . getDeclaredClasses ( ) ; 

Class ut = null; 

for(int j = 0; j < classes . length; j++) { 
// Skip inner classes that are 
// not derived from UnitTest: 
if ( ! UnitTest .class . 

isAssignableFrom (classes [j])) 
continue; 
ut = classes [ j ] ; 

break; // Finds the first test class only 

} 

// If it found an inner class, 
// that class must be static: 
if (ut != null) 
require ( 

Modif ier . isStatic (ut . getModif iers ( ) ) , 
"inner UnitTest class must be static"); 
// If it couldn't find the inner class, 
// maybe it's a regular class (for black- 
// box testing: 
if (ut == null) 

if (UnitTest .class . isAssignableFrom (c) ) 
ut = c ; 
require (ut != null, 

"No UnitTest class found"); 
require ( 

Modifier. isPub lie (ut. getModif iers ( ) ) , 
"UnitTest class must be public"); 

Method [ ] methods = ut . getDeclaredMethods ( ) ; 

for(int k = 0; k < methods . length; k++) { 
Method m = methods [k] ; 

// Ignore overridden UnitTest methods: 
if (m. getName ( ) . equals ( "cleanup" ) ) 

continue; 
// Only public methods with no 



// arguments and void return 
// types will be used as test code: 
if (m . getParameterTypes (). length == && 
m . getReturnType ( ) == void. class && 
Modifier . is Public (m. getModif iers ( ) ) ) 
// The name of the test is 
// used in error messages: 
UnitTest . testID = m. getName ( ) ; 
// A new instance of the 
// test object is created and 
// cleaned up for each test: 
Object test = ut . newlnstance ( ) ; 
m . invoke (test , new Object [0]); 
( (UnitTest)test) . cleanup ( ) ; 




} catch (Exception e) { 

e . printStackTrace ( System. err ) ; 

// Any exception will return a nonzero 

// value to the console, so that 

// 'make' will abort: 

System . exit ( 1 ) ; 

} 

// After all tests in this class are run, 
// display any results. If there were errors 
// abort 'make' by returning a nonzero value 
if (UnitTest . errors . size ( ) != 0) { 

Iterator it = UnitTest . errors . iterator () ; 

while (it .hasNext () ) 

System. err. print In (it. next () ) ; 

System . exit ( 1 ) ; 

} 

} 

///:- 



Automatically executing 
tests 



Exercises 

1. Install this book's source codetree and ensure that you have a 
make utility installed on your system (Gnu make is freely 

avail able on the internet at various locations). In TestDemo.java, 
un-comment test3( ), then type make and observe the results. 

2 . M odify TestDemo.java by addi ng a new test that throws an 
exception. Type make and observe the results. 

3. Modify your solutions to the exercises in Chapter 1 by adding 
unit tests. Write makefiles that incorporate the unit tests. 



3: Building 
application 
frameworks 



A n appl i cati on framework al I ows you to inherit from a cl ass or set of 
cl asses and create a new appl i cati on, reusi ng most of the code i n the 
existing classes and overriding one or moremethodsin order to 
customize the application to your needs. A fundamental concept in the 
application framework istheTemplateM ethod which istypically hidden 
beneath the covers and drives the application by calling the various 
methods in the base class (some of which you have overridden in order 
to create the application). 

For example, whenever you create an applet you're using an application 
framework: you inherit from J Applet and then override init( ).The 
applet mechanism (which is a Template M ethod) does the rest by drawing 
the screen, handling the event loop, resizing, etc. 



An important characteristic of theTemplateM ethod is that it is defined in 
the base class and cannot be changed. It's sometimes a private method 
but it's virtually always final. It calls other base-class methods (the ones 
you override) in order to do its job, but it is usually called only as part of 
an initialization process (and thus the client programmer isn't necessarily 
abletocall it directly). 

//: c03 : TemplateMethod . java 

// Simple demonstration of Template Method, 
import com . bruceeckel . test . * ; 




method 



abstract class ApplicationFramework { 



public ApplicationFramework ( ) { 
templateMethod ( ) ; // Dangerous! 

} 

abstract void customizel () ; 
abstract void customize2 ( ) ; 
// "private" means automatically "final": 
private void templateMethod ( ) { 
for(int i = 0; i < 5; i++) { 

customizel ( ) ; 

customize2 ( ) ; 




// Create a new "application": 
class MyApp extends ApplicationFramework { 
void customizel () { 

System. out .print ( "Hello "); 

} 

void customize2() { 

System. out .print In ( "World! " ) ; 

} 

} 

public class TemplateMethod extends UnitTest { 

MyApp app = new MyApp ( ) ; 

public void test() { 

// The MyApp constructor does all the work. 
// This just makes sure it will complete 
// without throwing an exception. 

} 

public static void main (String args [ ] ) { 
new TemplateMethod (). test () ; 

} 

} ///:- 



The base-cl ass constructor i s responsi bl e for perf ormi ng the necessary 
initialization and then starting the "engine" (thetemplate method) that 
runs the application (in a GUI application, this "engine" would be the 
mai n event I oop). The cl i ent programmer si mply provi des def i niti ons for 
customized ) and customize2( ) and the "application" is ready to run. 



4: Fronting for an 
implementation 

Both P roxy and State provide a surrogate cl ass that you use i n your code; 
the real class that does the work ishidden behind this surrogate class. 
When you call a method in the surrogate, it simply turns around and 
cal I s the method i n the i mpl ementi ng cl ass. These two patterns are so 
similar that the Proxy is simply a special case of State. One is tempted to 
justlump the two together into a pattern called Surrogate, but the term 
"proxy" has a long-standing and specialized meaning, which probably 
explains the reason for the two different patterns. 

The basic idea issimple: from a base class, thesurrogate is derived along 
w i th th e cl ass or cl asses th at pr ovi d e th e actu al i mp I ementati on : 



I nterface 



Surrogate 



I mplementationl 



I mplementation2 



Etc. 



Surrogate 




1 mplementation 





When a surrogate object is created, it is given an implementation to 
which to send all of the method calls. 

Structurally, the difference between Proxy and State is simple: a Proxy has 
only one i mpl ementati on, whi I e State has more than one. The appl i cati on 
of the patterns is considered (in Design Patterns) to bedisti net: Proxy is 
used to control access to its implementation, while State allows you to 
change the implementation dynamically. However, if you expand your 



notion of "controlling access to implementation" then the two fit neatly 
together. 



If we i mplement P roxy by fol lowi ng the above di agram, it looks I i ke this: 

//: cO 4 : ProxyDemo . java 

// Simple demonstration of the Proxy pattern, 
import com . bruceeckel . test .* ; 

interface ProxyBase { 
void f ( ) ; 
void g ( ) ; 
void h ( ) ; 



class Proxy implements ProxyBase { 
private ProxyBase implementation; 
public Proxy () { 

implementation = new Implementation () ; 

} 

// Pass method calls to the implementation: 
public void f() { implementation . f () ; } 
public void g() { implementation . g () ; } 
public void h() { implementation . h () ; } 



class Implementation implements ProxyBase { 
public void f ( ) { 

System . out . print In ( " Implementation . f ( ) " ) ; 

} 

public void g() { 

System . out . print In ( " Implementation . g ( ) " ) ; 

} 

public void h ( ) { 

System . out . print In ( " Implementation . h ( ) " ) ; 

} 




public class ProxyDemo extends UnitTest { 
Proxy p = new Proxy (); 
public void test() { 



// This just makes sure it will complete 
// without throwing an exception. 

P-f(); 
p . g ( ) ; 
p.h() ; 

} 

public static void main (String args [ ] ) { 
new ProxyDemo ( ) . test ( ) ; 

} 

} III:- 

Of course, it isn't necessary that I implementation have the same i nterface 
as Proxy; as long as Proxy is somehow "speaking for" the class that it is 
referring method callstothen the basic idea is satisfied (note that this 
statement is at odds with the definition for Proxy in GoF). However, it is 
convenient to havea common interface so that Implementation isforced 
to fulfil I all the methods that Proxy needs to call. 

State 

TheState pattern adds more implementations to Proxy, along with away 
to switch from one implementation to another duri ng the I ifeti me of the 
surrogate: 

//: cO 4 : StateDemo . java 

// Simple demonstration of the State pattern, 
import com . bruceeckel . test .* ; 

interface StateBase { 
void f () ; 
void g ( ) ; 
void h ( ) ; 

} 

class State implements StateBase { 
private StateBase implementation; 
public State (StateBase imp) { 
implementation = imp; 

} 

public void changelmp ( StateBase newlmp) { 
implementation = newlmp; 



} 

// Pass method calls to the implementation: 
public void f() { implementation . f () ; } 
public void g() { implementation . g () ; } 
public void h() { implementation . h () ; } 

} 

class Implementationl implements StateBase { 
public void f ( ) { 

System . out . print In ( " Implementationl . f ( ) " ) 

} 

public void g() { 

System . out . print In ( " Implementationl . g ( ) " ) 

} 

public void h ( ) { 

System . out . print In ( " Implementationl . h ( ) " ) 




class Implementation2 implements StateBase { 
public void f ( ) { 

System . out . print In ( " Implementation2 . f ( ) " ) 

} 

public void g() { 

System . out . print In ( " Implementation2 . g ( ) " ) 

} 

public void h ( ) { 

System . out . print In ( " Implement at ion2 . h ( ) " ) 




public class StateDemo extends UnitTest { 
static void run (State b) { 
b . f ( ) ; 
b . g ( ) ; 
b . h ( ) ; 

} 

State b = new State (new Implementationl ()) ; 

public void test() { 

// This just makes sure it will complete 
// without throwing an exception, 
run (b) ; 

b . changelmp (new Implementation2 ( ) ) ; 
run (b) ; 



} 

public static void main (String args [ ] ) { 
new StateDemo ( ) . test ( ) ; 

} 

} ///:- 

In main( ), you can see that the first implementation is used for a bit, then 
the second implementation is swapped in and that is used. 

The difference between Proxy and State is in the problems that are solved. 
The common uses for Proxy as described in Design Patterns are: 

1. Remote proxy. This proxies for an object in a different address 
space. A remote proxy is created for you automatically by the RM I 
compiler rmic as it creates stubs and skeletons. 

2. Virtual proxy. This provides "lazy initialization" to create 
expensive objects on demand. 

3. Protection proxy. Used when you don't want the client 
programmer to have full access to the proxied object. 

4. Smart reference. To add additional actions when the proxied 
object is accessed. For example, or to keep track of the number of 
references that are held for a particular object, in order to 

i mpl ement thecopy-on-writeidiomandpreventobjectaliasing.A 
simpler example is keeping track of the number of calls to a 
particular method. 

You could look at a Java reference as a kind of protection proxy, since it 
controls access to the actual object on the heap (and ensures, for example, 
that you don't use a null reference). 

[[ Rewrite this: In Design Patterns, Proxy and State are not seen as related 
to each other because the two are given (what I consider arbitrarily) 
different structures. State, in particular, uses a separate implementation 
hierarchy but this seems to me to be unnecessary unless you have 
decided that the implementation is not under your control (certainly a 
possibility, butif you own all the codethere seems to be no reason not to 
benefit from the elegance and hel pfulness of the singlebase class). In 
addition, Proxy need not use the same base class for its implementation, 
as I ong as the proxy object i s control ling access to the object i t "f ronti ng" 



for. Regard I ess of the specifics, in both Proxy and State a surrogate is 
passing method callsthrough to an implementation object.]]] 

StateMachine 

While State has a way to allow the client programmer to change the 
i mpl ementati on , S tateM ach i n e i mposes a stru ctu re to automati cal I y 
change the i mplementati on from one object to the next. The current 
implementation represents the state that a system is in, and thesystem 
beh aves d i ff erentl y from on e state to th e n ext ( becau se i t u ses S tate) . 
Basically, this is a "state machine" using objects. 

The code that moves the system from one state to the next i s often a 
Template M ethod, as seen in this example: 

// : c04 : statemachine : StateMachineDemo . java 

// Demonstrates StateMachine pattern 

// and Template method. 

package c04 . statemachine; 

import java . util . * ; 

import com . bruceeckel . test .* ; 

interface State { 
void run ( ) ; 

} 

abstract class StateMachine { 
protected State currentState; 
abstract protected boolean changeState () ; 
// Template method: 
protected final void runAll() { 

while ( changeState () ) // Customizable 
currentState . run ( ) ; 

} 



// A different subclass for each state: 

class Wash implements State { 
public void run ( ) { 

System . out . print In ( "Washing" ) ; 

} 



} 



class Spin implements State { 
public void run ( ) { 

System. out .println ( "Spinning" ) ; 




class Rinse implements State { 
public void run ( ) { 

System. out .println ( "Rinsing" ) ; 




class Washer extends StateMachine { 
private int i = 0; 
// The state table: 
private State states [] = { 

new Wash(), new Spin(), 

new Rinse (), new Spin(), 

}; 

public Washer () { runAll(); } 
public boolean changeState ( ) { 
if (i < states . length) { 

// Change the state by setting the 
// surrogate reference to a new object: 
currentState = states [ i++ ] ; 
return true; 
} else 

return false; 




public class StateMachineDemo extends UnitTest { 

Washer w = new Washer () ; 

public void test() { 

// The constructor does the work. 

// This just makes sure it will complete 

// without throwing an exception. 

} 

public static void main (String args [ ] ) { 
new StateMachineDemo () .test () ; 

} 

} ///:- 



H ere, the cl ass that control s the states (StateM ach i ne i n thi s case) i s 
responsible for deciding the next state to move to. Another approach is to 
allow the state objects themselves to decide what state to moveto next, 
typically based on some kind of input to the system. This is a more 
flexible solution. Here it is, and in addition the program is evolved to use 
2-d arrays to conf i gure the state machi nes: 

//: cO 4 : washer : Washer . java 

// An example of the State Machine pattern 

package c04. washer; 

import java . util . * ; 

import java.io.*; 

import com . bruceeckel . test .* ; 

class MapLoader { 

public static void load(Map m, Object [] [] pairs) { 
for(int i = 0; i < pairs . length; i++) 
m. put (pairs [ i ] [0], pairs[i] [1]); 

} 

} 

interface State { 

void run (String input); 

} 

public class Washer { 

private State currentState; 

static HashMap states = new HashMap (); 

public Washer () { 

states . put ( "Wash" , new Wash()); 
states .put ( "Rinse" , new Rinse (in- 
states . put (" Spin" , new Spin()); 
currentState = (State) states . get ( "Wash" ) ; 

} 

private void 

nextState (Map stateTable, String input) { 
currentState = (State) states . get ( 
stateTable . get (input) ) ; 

} 

class TState implements State { 

protected HashMap stateTable = new HashMap (); 



public void run (String input) { 

String name = getClass ( ) . toString ( ) ; 
System . out . print In ( 
name . substring ( 

name . lastlndexOf ("$") + 1 ) ) ; 
nextState ( stateTable, input); 

} 

} 

// A different subclass for each state: 
class Wash extends TState { 
{ 

MapLoader. load (stateTable, new String [] [] { 

{ "Wash", "Spin" }, 

{ "Spin", "Spin" }, 

{ "Rinse", "Rinse" } 
}) ; 

} 

} 

class Spin extends TState { 
{ 

MapLoader . load (stateTable, new String [] [] { 

{ "Wash", "Wash" }, 

{ "Spin", "Rinse" }, 

{ "Rinse", "Rinse" } 
}) ; 

} 

} 

class Rinse extends TState { 
{ 

MapLoader . load (stateTable, new String [] [] { 

{ "Wash", "Wash" }, 

{ "Spin", "Spin" }, 

{ "Rinse", "Spin" } 
}) ; 

} 

} 

public void run ( ) { 
try { 

Buf f eredReader inputStream = 

new Buf f eredReader ( 

new FileReader ("StateFile.txt") ) ; 
while (inputStream. ready () ) { 

// Get next state from file... 

String input = 



inputStream. readLine ( ) . trim ( ) ; 
if (input != null) 

currentState . run (input ) ; 

} 

inputStream. close (); 
} catch (IOException e) { 

e . printStackTrace ( System. err ) ; 

} 

} 

public static class Test extends UnitTest { 
Washer w = new Washer () ; 
public void test() { w.run(); } 

} 

public static void main (String args [ ] ) { 
new Test ( ) . test ( ) ; 

} 

} ///:- 



The i nput i s read from the f i I e StateFi I e.txt: 

//:! c04 :washer: StateFile.txt 

Wash 

Spin 

Rinse 

Spin 

Wash 

Spin 

Rinse 

Spin 

Wash 

Spin 

Rinse 

Spin 

Wash 

Spin 

Rinse 

Spin 

///:- 

If you look at the above program, you can easily see that having the 
proliferation of tables is annoying and messy to maintain. If you are 
going to be regularly configuring and modifying the state transition 



i nf ormati on, the best sol uti on i s to combi ne al I the state i nf ormati on i nto 
asingletable. This can be implemented using a Map of Maps, but at this 
point we might as well create a reusable tool for the job: 

// : com: bruceeckel :util:TransitionTable. java 

// Tool to assist creating & 

// using state transition tables 

package com. bruceeckel . util; 

import java . util . * ; 

public class TransitionTable { 
public static Map 

build (Ob ject [ ] [] [] table, Map m) { 

for(int i = 0; i < table . length; i++) { 
Object [] [] row = table [i] ; 
Object key = row[0][0]; 
Map val = new HashMapO; 
for(int j = 1; j < row. length; j++) 

val . put ( row [ j ] [ ] , row [ j ] [ 1 ] ) ; 
m. put (key, val ) ; 

} 

return m; 

} 

public interface Transitioner { 

Object nextState (Object curr, Object input); 

} 

// Default implementation and example 
// of nextState () method code: 
public static class StateChanger 

implements Transitioner { 

private Map map = new HashMapO; 

public StateChanger (Ob ject [][][ ] table) { 
TransitionTable . build (table, map) ; 

} 

public Object 

nextState (Ob ject curr, Object input) { 
return ( (Map) map. get (curr) ) .get (input) ; 

} 

} 

} ///:- 

Here is the unit test code that creates and runs an example transition 
table. It also includes a main( ) for convenience: 



//: c04 : TransitionTableTest . java 

// Unit test code for TransitionTable . java 

import com . bruceeckel . test .* ; 

import com . bruceeckel . util .* ; 



public class TransitionTableTest extends UnitTest- 
Object [] [] [] transitionTable = { 
{ {"one"}, // Current state 

// Pairs of input & new state: 
'one", "two"}, 
"two", "two"}, 
"three", "two"}}, 
"two"}, // Current state 
// Pairs of input & new state: 
'one", "three"}, 
"two", "three"}, 
"three", "three"}}, 
"three"}, // Current state 
// Pairs of input & new state: 
'one" , "one" } , 
"two", "one"}, 
"three", "one"}}, 



TransitionTable . StateChanger m = 
new TransitionTable . StateChanger ( 
transitionTable) ; 

public void test() { 

System . out . print In (m) ; 
String current = "one"; 

String [] inputs = { "one", "two", "three" 
for(int i = 0; i < 20; i++) { 
String input = inputs [ 

(int) (Math . random ( ) * inputs . length) ] ; 
System . out . print (" input = " + input); 
current = 

(String) m. nextState (current, input) ; 
System. out .print In ( 

", new state = " + current); 



public static void main ( String [ ] args) 
new TransitionTableTest () .test () ; 



} ///: 



Tools 



Another approach, as your state machi ne gets bigger, is to use an 
automation tool whereby you configure a table and let the tool generate 
the state machi ne code for you. This can be created yourself usi ng a 
languag e I ike Python, but there are also free, open-source tools such as 
Libero, at http:/ / www.imatix.com 



1. Create an example of the "virtual proxy." 

2 . C reate an examp I e of th e " Smart ref eren ce" p roxy w h ere you keep 
count of the number of method calls to a particular object. 

3. Using the State, make a class called UnpredictablePerson which 
changes the kind of response to its hello( ) method depending on 
what kind of Mood it's in. Add an additional kind of Mood called 
Prozac. 

4. Create a simple copy-on write implementation. 

5. ApplyTransitionTable.javatothe"Washer" problem. 

6. Create a StateM achine system whereby the cur rent state along 
with i nput i nformati on determi nes the next state that the system 
will be in. To do this, each state must store a reference back to the 
proxy object (the state control I er) so that it can request the state 
change. Use a H ashM ap to create a table of states, where the key 
is a String naming the new state and thevalueisthenew state 
object. Insideeach state subclass override a method nextState( ) 
that has its own state-transition table. The input to nextState( ) 
should beasingleword that comes from a text file containing one 
word per line. 




7 . M odify the previ ous exercise so that the state machi ne can be 
configured by creating/ modifying a single multi-dimensional 
array. 



X: Iterators: 
decoupling 
algorithms from 
containers 

A lexander Stepanov thought for years about the problem 
of generic programming techniques before creating the 
STL (along with DaveMusser). He came to the conclusion 
that all algorithms are defined on algebraic structures - 
what we would call containers. 

I n the process, he real i zed that iterators are central to the use of 
algorithms, because they decouplethe algorithms from the specific type 
of container that the algorithm might currently beworking with. This 
means that you can describe the algorithm without worrying about the 
particular sequence it is operating on. More generally, any code that you 
write using iterators is decoupled from the data structure that the code is 
manipulating, and thus your code is more general and reusable. 

The use of iterators also extends your code into the realm of functional 
programming, whose objective is to describe what a program is doing at 
every step rather than how it is doing it. That is, you say "sort" rather 
than describing the sort. The objective of the C++ STL was to providethis 
generic programming approach for C++(how successful this approach will 
actually be remains to be seen). 

If you've used containers in Java (and it's hard to write code without 
using them), you've used iterators - in theform of the Enumeration in 
Java 1.0/ Hand the Iterator in Java 2. So you should already be familiar 



with their general use. If not, see Chapter 9, H olding Your Objects, under 
Iterators in Thinking in Java, 2 nd edition (freely down load able from 
www.BruceEckd.com). 

Because the Java 2 containers rely heavily on iterators they become 
excel I ent candi dates for generi c/ fundi onal programmi ng techni ques. 
This chapter will explore these techni ques by converting the STL 
algorithms to Java, for use with the Java 2 container library. 

Type- safe iterators 

In Thinking in Java, 2 nd edition, I show the creation of a type-safe container 
that will only accept a particular type of object. A reader, Linda 
Pazzaglia, asked for the other obvious type-safe component, an iterator 
that would work with thebasicjava.util containers, but impose the 
constraint that the type of objects that it iterates over be of a particular 
type. 

If Java ever includes a template mechanism, this kind of iterator will have 
the added advantage of being able to return a specific type of object, but 
without templates you are forced to return generic Objects, or to require 
a bit of hand-coding for every type that you want to iterate through. I 
will take the former approach. 

A second design decision involves the time that the type of object is 
determined. One approach isto takethetype of thefirst object that the 
iterator encounters, but this is problematic because the containers may 
rearrange the objects according to an internal ordering mechanism (such 
asa hash table) and thus you may get different results from oneiteration 
to the next. The safe approach isto require the user to establish the type 
during construction of the iterator. 

Lastly, how do we build the iterator? We cannot rewrite the existing Java 
library classes that already produce Enumerations and Iterators. 
H owever, we can use the D ecorator design pattern, and create a class that 
simply wraps the Enumeration or Iterator that is produced, generating a 
new object that has the iteration behavior thatwewant (which is, inthis 
case, to throw a RuntimeException if an incorrect type is encountered) 
but with the same interface as the original Enumeration or Iterator, so 
that it can be used in the same pi aces (you may arguethat this is actually 



a Proxy pattern, but it's more likely Decorator because of its intent). Here 
is the code: 

// : com: bruceeckel : util : Typedlterator . java 
package com. bruceeckel . util; 
import java . util . * ; 

public class Typedlterator implements Iterator { 
private Iterator imp; 
private Class type; 

public Typedlterator ( Iterator it, Class type) { 
imp = it; 
this. type = type; 

} 

public boolean hasNext() { 
return imp . hasNext ( ) ; 

} 

public void remove ( ) { imp . remove () ; } 
public Object next () { 

Object obj = imp. next (); 
if ( ! type . is Instance (ob j ) ) 

throw new ClassCastException ( 

"Typedlterator for type " + type + 
" encountered type: " + ob j . getClass ( ) ) ; 
return obj; 

} 

} ///:- 



5: Factories: 
encapsulating 
object creation 

When you discover that you need to add new types to a system, the most 
sensiblefirststep is to use polymorphism to create a common interface to 
those new types. This separates the rest of the code i n your system from 
the knowledge of the specific types that you are adding. New types may 
be ad d ed w i th ou t d i stu r bi ng exi sti n g cod e . . . or so i t seems. At first it 
would appear that the only pi ace you need to change the code in such a 
design is the place where you inherita new type, but this is not quite 
true. You must sti 1 1 create an object of your new type, and at the poi nt of 
creati on you must specify the exact constructor to use. Thus, if the code 
that creates objects is distributed throughout your application, you have 
the same problem when adding new types— you must still chasedown 
all the points of your code where type matters. It happens to be the 
creation of the type that matters in this case rather than the use of thetype 
(which istaken care of by polymorphism), but the effect is the same: 
adding a new type can cause problems. 

Thesolution is to force the creati on of objects to occur through acommon 
factory rather than to allow the creati onal codeto bespread throughout 
your system. If all the code in your program must go through this factory 
whenever it needs to create one of your objects, then all you must do 
when you add a new object is to modify thefactory. 

Since every object-oriented program creates objects, and sinceit'svery 
likely you will extend your program by adding new types, I suspect that 
factories may be the most universally useful kinds of design patterns. 



imple Factory method 

As an example, let's revisit the Shape system. Si nee the factory may fail 
in its creation of a requested Shape, an appropriate exception is needed: 

// : cO 5 : badshape : BadShapeCreation . java 
package cO 5 .badshape; 

public class BadShapeCreation extends Exception { 
public BadShapeCreation ( String msg) { 
super (msg) ; 

} 

}///:- 



One approach i s to make the factory a stati c method of the base cl ass: 

// : c05 : shapef actl : ShapeFactoryl . java 

// A simple static factory method. 

package cO 5 . shapef actl ; 

import c05 .badshape . *; 

import java . util . * ; 

import com . bruceeckel . test .* ; 

abstract class Shape { 

public abstract void draw ( ) ; 
public abstract void erase (); 
public static Shape factory (String type) 
throws BadShapeCreation { 

if (type . equals ( "Circle" ) ) return new Circle (); 
if (type . equals (" Square ") ) return new Square (); 
throw new BadShapeCreation (type ) ; 

} 



class Circle extends Shape { 

Circle () {} // Friendly constructor 
public void draw ( ) { 

System. out .print In ( "Circle . draw" ) ; 

} 

public void erase () { 

System. out .print In ( "Circle . erase" ) ; 

} 



class Square extends Shape { 

Square () {} // Friendly constructor 
public void draw ( ) { 

System . out . print In ( " Square . draw" ) ; 

} 

public void erase () { 

System. out .println ( "Square . erase" ) ; 

} 



public class ShapeFactoryl extends UnitTest { 
String shlist[] = { "Circle", "Square", 

"Square", "Circle", "Circle", "Square" } ; 
List shapes = new ArrayList ( ) ; 
public void test() { 
try { 

for(int i = 0; i < shlist . length; i++) 
shapes . add (Shape . factory ( shlist [ i ])) ; 
} catch (BadShapeCreation e) { 
e . printStackTrace ( System. err ) ; 
assert (false) ; // Fail the unit test 

} 

Iterator i = shapes . iterator () ; 
while ( i . hasNext () ) { 

Shape s = (Shape) i . next () ; 

s . draw ( ) ; 

s . erase ( ) ; 




public static void main (String args [ ] ) { 
new ShapeFactoryl () .test () ; 

} 

} ///:- 

Thefactory( ) takes an argument that allows itto determine what type of 
Shape to create; it happens to be a String in this case but it could beany 
set of data. Thefactory( ) is now the only other code in thesystem that 
needs to be changed when a new type of Shape is added (the 
initialization data for the objects will presumably come from somewhere 
outside the system, and not be a hard-coded array as in the above 
example). 



To encourage creation to only happen in thefactory( ), the constructors 
for the specific types of Shape are made "friendly," sofactory( ) has 
access to the constructors but they are not avai I abl e outsi de the package. 

Polymorphic factories 

The static factory( ) method in the previous example forces all the 
creation operations to be focused in one spot, so that's the only place you 
need to change the code. This is certainly a reasonable solution, as it 
throws a box around the process of creating objects. H owever, the D esign 
Patterns book emphasizes that the reason for theFactory M ethod pattern is 
so that d i fferent types of f actori es can be su bcl assed from the basi c 
factory (the above design is mentioned as a special case). H owever, the 
book does not providean example, but instead just repeats the example 
used for the Abstract Factory (you'll see an exampleof this in the next 
section). H ere is ShapeFactoryl.java modified so thefactory methods are 
in a separate class as virtual functions. Notice also that the specific Shape 
classes are dynamically loaded on demand: 

// : c05 : shapef act2 : ShapeFactory2 . java 

// Polymorphic factory methods. 

package cO 5 . shapef act2 ; 

import c0 5 .badshape . *; 

import java . util . * ; 

import com . bruceeckel . test .* ; 

interface Shape { 
void draw ( ) ; 
void erase ( ) ; 

} 

abstract class ShapeFactory { 

protected abstract Shape create () ; 

private static Map factories = new HashMap ( ) ; 

public static void 

addFactory (String id, ShapeFactory f) { 
factories . put ( id, f ) ; 

} 

// A Template Method: 

public static final Shape createShape (String id) 
throws BadShapeCreation { 



if (! factories . containsKey (id) ) { 
try { 

// Load dynamically 

Class . forName ( "c05 . shapefact2 . " + id); 
} catch (ClassNotFoundException e) { 
throw new BadShapeCreation ( id) ; 

} 

// See if it was put in: 
if ( ! factories . containsKey (id) ) 
throw new BadShapeCreation ( id) ; 

} 

return 

( (ShapeFactory) factories . get (id) ) . create ( ) ; 

} 

} 

class Circle implements Shape { 
private Circle () {} 
public void draw ( ) { 

System. out .println ( "Circle . draw" ) ; 

} 

public void erase () { 

System. out. print In ("Circle. erase") ; 

} 

private static class Factory 
extends ShapeFactory { 

protected Shape create () { 
return new Circle (); 

} 

} 

static { 

ShapeFactory . addFactory ( 

"Circle", new Circle . Factory ()) ; 

} 

} 

class Square implements Shape { 
private Square () {} 
public void draw ( ) { 

System . out .println ( " Square . draw" ) ; 

} 

public void erase () { 

System. out .println ( "Square . erase" ) ; 

} 



private static class Factory 
extends ShapeFactory { 

protected Shape create () { 
return new Square (); 

} 

} 

static { 

ShapeFactory . addFactory ( 

"Square", new Square . Factory ()) ; 

} 

} 

public class ShapeFactory2 extends UnitTest { 
String shlist[] = { "Circle", "Square", 

"Square", "Circle", "Circle", "Square" } ; 
List shapes = new ArrayList ( ) ; 
public void test() { 

// This just makes sure it will complete 

// without throwing an exception. 

try { 

for(int i = 0; i < shlist . length; i++) 
shapes . add ( 

ShapeFactory . createShape ( shlist [ i ])) ; 
} catch (BadShapeCreation e) { 
e.printStackTrace ( System. err) ; 
assert (false) ; // Fail the unit test 

} 

Iterator i = shapes . iterator () ; 
while ( i . hasNext () ) { 

Shape s = (Shape) i . next () ; 

s . draw ( ) ; 

s . erase ( ) ; 

} 

} 

public static void main (String args [ ] ) { 
new ShapeFactory2 () .test () ; 

} 

} ///:~ 

Now thefactory method appearsin its own class, ShapeFactory, as the 
create( ) method. This is a protected method which means it cannot be 
called directly, but it can be overridden. Thesubclasses of Shape must 
each create their own subclasses of ShapeFactory and overridethe 



create( ) method to create an object of thei r ow n type. The actual creati on 
of shapes is performed by calling ShapeFactory.createShape( ), which is 
a stati c method that uses the M ap i n ShapeFactory to f i nd the 

appropriate factory object based on an identifier that you pass it. The 
factory is immediately used to create the shape object, but you could 
i magi ne a more compl ex probl em w here the appropri ate factory object i s 
returned and then used by the cal ler to create an object i n a more 
sophisticated way. However, it seems that much of the time you don't 
need the intricacies of the polymorphic factory method, and asingle 
static method in the base class (as shown in ShapeFactory l.java) will 
work fine. 

Notice that the ShapeFactory must be initialized by loading its Map with 
factory objects, which takes place in the static initialization clause of each 
of the Shape implementations. So to add a new type to this design you 
must inherit the type, create a factory, and add the static initialization 
clause to load theM ap. This extra complexity again suggests the use of a 
static factory method if you don't need to create i ndividual factory 
objects. 

Abstract factories 

TheAbstract Factory pattern looks I ike the factory objects we've seen 
previously, with not one but several factory methods. Each of the factory 
methods creates a different kind of object. The idea is that at the point of 
creation of the factory object, you decide how all the objects created by 
that factory will be used. The example given in Design Patterns 
implements portability across various graphical user i nterf aces (GUIs): 
you create a factory object appropri ate to theGUI that you're working 
with, and from then on when you ask it for a menu, button, slider, etc. it 
will automatically create the appropri ate version of that item for the GUI. 
Thus you're able to isolate, in one place, the effect of changing from one 
GUI to another. 

As another exampl e suppose you are creati ng a general-purpose garni ng 
environment and you want to be able to sup port different types of 
games. H ere's how it mi ght I ook usi ng an abstract factory: 

//: cO 5 : Games . java 

// An example of the Abstract Factory pattern. 



import com . bruceeckel . test .* ; 

interface Obstacle { 
void action ( ) ; 

} 

interface Player { 

void interactWith (Obstacle o) ; 

} 

class Kitty implements Player { 

public void interactWith (Obstacle ob) { 

System . out . print ( "Kitty has encountered a "); 
ob . action ( ) ; 




class KungFuGuy implements Player { 

public void interactWith (Obstacle ob) { 

System . out . print ( "KungFuGuy now battles a "); 
ob . action ( ) ; 




class Puzzle implements Obstacle { 
public void action () { 

System. out .print In ( "Puzzle" ) ; 




class NastyWeapon implements Obstacle { 
public void action () { 

System. out .println ( "NastyWeapon" ) ; 




// The Abstract Factory: 
interface GameElementFactory { 

Player makePlayer ( ) ; 

Obstacle makeObstacle ( ) ; 

} 

// Concrete factories: 
class KittiesAndPuzzles 



implements GameElementFactory { 
public Player makePlayer ( ) { 
return new Kitty (); 

} 

public Obstacle makeObstacle ( ) { 
return new Puzzle () ; 

} 



class KillAndDismember 
implements GameElementFactory { 
public Player makePlayer () { 
return new KungFuGuy ( ) ; 

} 

public Obstacle makeObstacle ( ) { 
return new NastyWeapon ( ) ; 

} 

} 

class GameEnvironment { 

private GameElementFactory gef; 
private Player p; 
private Obstacle ob; 
public GameEnvironment ( 

GameElementFactory factory) { 

gef = factory; 

p = factory . makePlayer () ; 

ob = factory . makeObstacle () ; 

} 

public void play() { p . interactWith (ob) ; } 



public class Games extends UnitTest { 
GameElementFactory 

kp = new KittiesAndPuzzles ( ) , 

kd = new KillAndDismember () ; 
GameEnvironment 

gl = new GameEnvironment (kp) , 

g2 = new GameEnvironment (kd) ; 
// These just ensure no exceptions are thrown: 
public void testl() { gl.playO; } 
public void test2() { g2.play(); } 
public static void main (String args [ ] ) { 

Games g = new Games () ; 



g. testl () ; 
g . test 2 () ; 

} 

} ///:- 

In this environment, Player objects interact with Obstacle objects, but 
there are different types of players and obstacles depending on what 
kind of game you're playing. You determine the kind of game by 
choosing a particular GameElementFactory, and then the 
GameEnvironmentcontrolsthesetup and play of the game. In this 
exampl e, the setup and pi ay i s very si mpl e, but those acti vi ti es (the initial 
conditions and the state change) can determine much of the game's 
outcome. Here, GameEnvironment is not designed to be inherited, 
although it could very possibly makesenseto do that. 

This also contains examples of Double Dispatching and the Factory M ethod, 
both of which will be explained later. 



1. Add a class Triangle to ShapeFactoryl.java 

2. Add a class Triangle to ShapeFactory2.java 

3. Add a new type of GameEnvironment called GnomesAnd Fairies 
to G ameE nvi ronment.j ava 

4. M odify ShapeFactory2.java so that it uses an A bstract Factory to 
create different sets of shapes (for example, one particular type of 
factory object creates "thick shapes," another creates "thin 
shapes," but each factory object can create al I the shapes: ci rd es, 
squares, triangles etc.). 




6: Function objects 



In Advanced C++:Programming Styles And Idioms (Addison -Wesley, 1992), 
Jim Coplien coins the term "functor" which is an object whose sole 
purpose is to encapsulate a function. The point is to decouplethe choice 
of function to be called from the site where that function iscalled. 

This term is mentioned but not used in Design Patterns. However, the 
theme of the functor is repeated in a number of patterns in that book. 

Command 

This isthe functor in its purest sense: a method that'san objectH By 
wrappi ng a method i n an object, you can pass it to other methods or 
objects as a parameter, to tell them to perform this particular operation in 
the process of fulfilling your request. 

//: cO 6 : CommandPattern . java 

import java . util . * ; 

import com . bruceeckel . test .* ; 

interface Command { 
void execute ( ) ; 

} 

class Hello implements Command { 
public void execute () { 

System. out .print ( "Hello "); 

} 

} 

class World implements Command { 
public void execute () { 

System . out . print ( "World ! "); 



1 In the Python language, all functions are already objects and so the Command 
pattern is often redundant. 



} 

} 



class I Am implements Command { 
public void execute () { 

System . out . print (" I ' m the command pattern!"); 




// An object that holds commands: 
class Macro { 

private List commands = new ArrayList ( ) ; 
public void add(Command c) { commands . add (c) ; } 
public void run ( ) { 

Iterator it = commands . iterator () ; 
while (it .hasNext () ) 

( (Command) it . next ( ) ) . execute ( ) ; 




public class CommandPattern extends UnitTest { 
Macro macro = new Macro ( ) ; 
public void test() { 

macro . add (new Hello ()); 

macro . add (new WorldO); 

macro . add (new I Am ( ) ) ; 

macro . run ( ) ; 

} 

public static void main (String args [ ] ) { 
new CommandPattern (). test () ; 

} 

} ///:- 



The primary point of Command isto allow you to hand adesired action to 
a method or object. I n the above example, this provi des a way to queue a 
set of actions to be performed collectively. In this case, it allows you to 
dynamically create new behavior, something you can normally only do 
by writing new code but in the above example could bedoneby 
interpreting a script (see the Interpreter pattern if what you need to do 
gets very complex). 

Another example of Command iscl2:DirList.java. TheDirFilter class is 
the command object which contains its action in the method accept( ) that 



is passed tothelist( ) method. The I ist( ) method determines what to 
i nd ude i n its result by cal I i ng accept( ). 

Design Patterns says that "Commands are an object-oriented replacement 
for call backsW" However, I think that the word "back" is an essential part 
of the concept of callbacks. Thatis, I think a callback actually reaches 
back to the creator of the cal I back. On the other hand, with a Command 
object you typically just create it and hand it to some method or object, 
and are not otherwise connected over time to the Command object. That's 
my takeon it, anyway. Later in this book, I combinea group of design 
patterns under the heading of "callbacks." 

Strategy 

Strategy appears to be a family of Command classes, all inherited from the 
same base. But if you look at Command, you'll seethatithasthesame 
str u ctu re: a h i erar chy of f u n ctors. Th e d i f f eren ce i s i n th e w ay th i s 
hierarchy is used. As seen in cl2:DirList.java, you use Command to solve 
a particular problem— in that case, selecting files from a list. The "thing 
that stays the same" is the body of the method that's bei ng cal led, and the 
part that varies is isolated in thefunctor. I would hazard to say that 
C om man d provi d es f I exi bi I i ty w h i I e you ' re w ri ti ng the program, w hereas 
Strategy's flexibility is at run time. Nonetheless, it seems a rather fragile 
distinction. 

Strategy also adds a "Context" which can be a surrogate class that 
controls the selection and use of the particular strategy object— just like 
State! Here's what it looks like: 

// : cO 6 : strategy : StrategyPattern . java 
package cO 6 . strategy ; 

import com . bruceeckel . util . * ; // Arrays2 . print ( ) 
import com . bruceeckel . test .* ; 

// The strategy interface: 
interface FindMinima { 

// Line is a sequence of points: 



2 Page 235. 



doublet] algorithm (double [ ] line); 

} 

// The various strategies: 

class LeastSquares implements FindMinima { 
public doublet] algorithm (double [ ] line) { 
return new double [ ] { 1.1, 2.2 }; // Dummy 




class Perturbation implements FindMinima { 
public doublet] algorithm (double [ ] line) { 
return new doublet] { 3.3, 4.4 }; // Dummy 




class Bisection implements FindMinima { 

public doublet] algorithm (double [ ] line) { 
return new doublet] { 5.5, 6.6 }; // Dummy 




// The "Context" controls the strategy: 
class MinimaSolver { 

private FindMinima strategy; 

public MinimaSolver (FindMinima strat) { 
strategy = strat; 

} 

doublet] minima (double [ ] line) { 
return strategy . algorithm (line) ; 

} 

void changeAlgorithm (FindMinima newAlgorithm) { 
strategy = newAlgorithm; 

} 



public class StrategyPattern extends UnitTest { 
MinimaSolver solver = 

new MinimaSolver (new LeastSquares ()) ; 
double [ ] line = { 

1.0, 2.0, 1.0, 2.0, -1.0, 

3.0, 4.0, 5.0, 4.0 }; 
public void test() { 

Arrays 2 .print (solver. minima (line) ) ; 



solver . changeAlgorithm (new Bisection ( ) ) ; 
Arrays 2 .print (solver. minima (line) ) ; 

} 

public static void main (String args [ ] ) { 
new StrategyPattern ( ) . test ( ) ; 

} 

} ///:- 



Chain of responsibility 

Chain of Responsibility might bethought of as a dynamic generalization of 
recursion using Strategy objects. You makea call, and each Strategy in a 
I i nked sequence tri es to satisfy the cal I . The process ends when one of the 
strategies is successful or the chain ends. In recursion, one method calls 
itself over and over until a termination condition is reached; with Chain of 
Responsibility, a method cal Is the same base- class method (with different 
i mpl ementati ons) w hi ch cal I s another i mpl ementati on of the base-cl ass 
method, etc., until atermination condition is reached. 

Instead of calling a single method to satisfy a request, multiple methods 
i n the chai n have a chance to sati sfy the request, so it has the f I avor of an 
expert system. Si nee the chain is effectively a linked list, it can be 
dynamically created, so you could also think of it as a more general, 
dynamically-built switch statement. 

In Strategy Pattern Java, above, what you probably want is to 
automatically find a solution. Chain of Responsibility provides a way to do 
this: 

// : cO 6 : Chai nOf Responsibility . java 

import com . bruceeckel . util . * ; // Arrays2 . print ( ) 

import com . bruceeckel . test .* ; 

import java . util . * ; 

class FindMinima { 

private FindMinima successor = null; 
public void add (FindMinima succ) { 

FindMinima end = this; 

while (end. successor != null) 



end = end. successor; // Traverse list 
end. successor = succ; 

} 

public doublet] nextAlgorithm (double [ ] line) { 
if (successor != null) 

// Try the next one in the chain: 
return successor . algorithm ( line ) ; 
else 

return new doublet] { } ; // Nothing found 

} 

public doublet] algorithm (double [ ] line) { 
// FindMinima algorithm () is only the 
// start of the chain; doesn't actually try 
// to solve the problem: 
return nextAlgorithm (line) ; 



lass LeastSquares extends FindMinima { 
public doublet] algorithm (double [ ] line) { 

System. out .println ( "LeastSquares . algorithm" ) ; 
boolean weSucceed = false; 

if (weSucceed) // Actual test/calculation here 
return new doublet] { 1.1, 2.2 }; // Dummy 

else // Try the next one in the chain: 
return nextAlgorithm (line) ; 

} 



lass Perturbation extends FindMinima { 
public doublet] algorithm (double [ ] line) { 

System . out . println ( "Perturbation . algorithm" ) ; 
boolean weSucceed = false; 

if (weSucceed) // Actual test/calculation here 
return new doublet] { 3.3, 4.4 }; // Dummy 

else // Try the next one in the chain: 
return nextAlgorithm (line) ; 

} 



lass Bisection extends FindMinima { 
public doublet] algorithm (double [ ] line) { 
System. out. print In ("Bisection. algorithm" ) ; 
boolean weSucceed = true; 



if (weSucceed) // Actual test/calculation here 

return new doublet] { 5.5, 6.6 }; // Dummy 
else 

return nextAlgorithm (line) ; 

} 

} 

// The "Handler" proxies to the first functor: 
class MinimaSolver { 

private FindMinima chain = new FindMinima () ; 

void add (FindMinima newAlgorithm) { 
chain . add (newAlgorithm) ; 

} 

// Make the call to the top of the chain: 
doublet] minima (double [ ] line) { 
return chain . algorithm (line) ; 

} 

} 

public 

class ChainOf Responsibility extends UnitTest { 
MinimaSolver solver = new MinimaSolver () ; 
double [ ] line = { 

1.0, 2.0, 1.0, 2.0, -1.0, 

3.0, 4.0, 5.0, 4.0 }; 
public void test() { 

solver . add (new LeastSquares ( ) ) ; 

solver . add (new Perturbation ()) ; 

solver . add (new Bisection ()) ; 

Arrays 2 .print (solver. minima (line) ) ; 

} 

public static void main (String args [ ] ) { 
new ChainOf Responsibility ( ) . test(); 

} 

} ///:- 



Exercises 



1. Modify ChainOf Responsibility Java so that it uses an ArrayList 

to hoi d the different strategy objects. Use Iterators to keep track 



of the current item and tomovetothenextone. Does this 
implement the Chain of Responsibility according to GoF? 

2 . I mplement Chai n of Responsibil ity to create an "expert system" 
that solves problems by successively trying onesolution after 
another until one matches. You should beableto dynamically add 
sol uti ons to the expert system. The test for sol uti on shoul d just be 
a string match, but when a sol uti on fits, the expert system should 
return the appropriate type of ProblemSolver object. What other 
pattern/ patterns show up here? 



7: Changing the 
interface 



Someti mes the probl em that you're sol vi ng i s as si mpl e as " I d on't have 
the interface that I want." Two of the patterns in Design Patterns solve 
this problem: Adapter takes one type and produces an interface to some 
other type. Facade creates an interface to a set of classes, simply to provide 
a more comfortable way to deal with a library or bundle of resources. 



When you've got this, and you need that, Adapter solves the problem. The 
only requi rement is to produce a that, and there are a number of ways 
you can accomplish this adaptation. 

//: cO 7 : Adapter . java 

// Variations on the Adapter pattern, 
import com . bruceeckel . test .* ; 

class WhatlHave { 
public void g ( ) { } 
public void h ( ) { } 

} 

interface WhatlWant { 
void f ( ) ; 

} 

class ProxyAdapter implements WhatlWant { 
WhatlHave whatlHave; 

public ProxyAdapter (WhatlHave win) { 
whatlHave = wih; 

} 

public void f ( ) { 

// Implement behavior using 
// methods in WhatlHave: 




what I Have . g ( ) ; 
what I Have . h ( ) ; 




class WhatlUse { 

public void op (WhatlWant wiw) { 
wiw . f ( ) ; 

} 

} 

// Approach 2: build adapter use into op ( ) : 
class WhatIUse2 extends WhatlUse { 
public void op (WhatlHave wih) { 
new ProxyAdapter (wih) . f ( ) ; 

} 

} 

// Approach 3: build adapter into WhatlHave: 
class WhatIHave2 extends WhatlHave 
implements WhatlWant { 
public void f ( ) { 

g() ; 
h() ; 




// Approach 4: use an inner class: 
class WhatIHave3 extends WhatlHave { 

private class InnerAdapter implements WhatlWant { 
public void f ( ) { 

g(); 
h() ; 

} 

} 

public WhatlWant whatIWant() { 
return new InnerAdapter () ; 

} 



public class Adapter extends UnitTest { 
WhatlUse whatlUse = new WhatlUse (); 
WhatlHave whatlHave = new WhatlHave () ; 
WhatlWant adapt= new ProxyAdapter (whatlHave ) ; 



WhatIUse2 whatIUse2 = new WhatIUse2 ( ) ; 
WhatIHave2 whatIHave2 = new WhatIHave2 ( ) ; 
WhatIHave3 whatIHave3 = new WhatIHave3 ( ) ; 
public void test() { 

what IUse . op ( adapt ) ; 

// Approach 2: 

whatIUse2 . op (whatlHave) ; 

// Approach 3: 

whatlUse . op (whatIHave2 ) ; 

// Approach 4: 

whatlUse . op (whatIHave3 . whatlWant ( ) ) ; 



I'mtaking libertieswith theterm "proxy" here, becausein Design Patterns 
they assert that a proxy must have an identical interface with the object 
that it is a surrogate for. However, if you have the two words together: 
"proxy adapter," it is perhaps more reasonable. 



A general principle that I apply when I'm casting about trying to mold 
requirements into a first-cut object is "If something is ugly, hide it inside 
an object." This is basically what Facade accomplishes. If you havea 
rather conf usi ng col I ecti on of cl asses and i nteracti ons that the cl i ent 
programmer doesn't really need to see, then you can create an interface 
that is useful for the client programmer and that only presents what's 
necessary. 

Fagadeisoften implemented as singleton abstract factory. Of course, you 
can easily get this effect by creating a class containing static factory 
methods: 

//: c07 : Facade . java 

import com . bruceeckel . test .* ; 



public static void main (String args [ ] ) { 
new Adapter ( ) . test ( ) ; 



} ///:- 




class A { public A(int x) {} } 
class B { public B(long x) {} } 



class C { public C (double x) { } } 



// Other classes that aren't exposed by the 
// facade go here . . . 

public class Facade extends UnitTest { 

static A makeA(int x) { return new A(x); } 
static B makeB(long x) { return new B (x) ; } 
static C makeC (double x) { return new C (x) ; } 
// The client programmer gets the objects 
// by calling the static methods: 
A a = Facade . makeA ( 1 ) ; 
B b = Facade . makeB ( 1 ) ; 
C c = Facade. makeC (1.0) ; 
public void test() {} 

public static void main (String args [ ] ) { 
new Facade (). test () ; 

} 

} ///:- 



The example given in Design Patterns isn't really a Facade but just a class 
that uses the other cl asses. 

Package as a variation of Fagade 

To me, the Fagade has a rather "procedural" (non-object-oriented) feel to 
it: you are just calling some functions to giveyou objects. And how 
different i s it, real ly, from A bstract F actory ? The poi nt of F acade i s to hi de 
part of a library of classes (and their interactions) from the client 
programmer, to make the interface to that group of classes more 
digestible and easier to understand. 

However, this is precisely what the packaging features in Java 
accomplish: outsideof the library, you can only create and use public 
classes; all the non-public classes are only accessible with in the package. 
It's as if Facade is a built-in feature of Java. 

Tobefair, Design Patterns iswritten primarily for a C++ audience. 
Although C++ has namespaces to prevent clashes of global sand class 
names, thi s does not provi de the cl ass hi di ng mechanism that you get 



with non-public cl asses i n J ava. Th e maj or i ty of th e ti me I th i n k th at J ava 
packages w i 1 1 sol ve the F acade probl em. 

Exercises 

1. Thejava.util.Map has no way to automatically load a two- 
dimensional array of objects into a M ap as key-value pairs. Create 
an adapter class that does this. 



2. 



8: Table-driven 
code: 

configuration 
flexibility 

Table-driven code using 
anonymous inner 
classes 

See ListPerformance.java example in Tl J from Chapter 9 
A I so G reen H ouse.j ava 



9: Interpreter/ 
Multiple 
Languages 

This chapter looks at the value of crossing language boundaries. That is, 
it is often very advantageous to solve a problem using more than one 
programming language, rather than being arbitrarily stuck using a single 
language. As you'll see in this chapter, often a problem that is very 
difficult or tedious to solve in one language can be solved quickly and 
easily in another. If you can combine the use of languages, you can often 
create your product much more quickly and cheaply. 

The most straightforward use of thisidea is the Interpreter design pattern, 
which adds an interpreted language to your program to allow the end 
user to easily customize a solution. In Java, the easiest and most powerful 
way todothisiswithJythonMan implementation of the Python language 
in purejava byte codes. 

I nterpreter solves a particular problem - that of creating a scripting 
language for the user. But sometimes it's just easier and faster to 
temporarily step into another language to solve a particular aspect of 
your problem. You're not creating an interpreter, you're just writing 
some code in another language. A gain, J ython isagood example of this, 
but CORBA also allows you to cross language boundaries. 



1 The original version of this was called J Python, but the project changed and the 
name was changed to emphasize the distinctness of the new version. 



I nterpreter 

If the application user needs greater run time flexibility, for example to 
create scri pts descri bi ng the desi red behavior of the system, you can use 
the I nterpreter design pattern. Here, you create and embed a language 
interpreter into your program. 

Motivation 

Remember that each desi gn pattern al I ows one or more factors to change, 
so it's important to first be aware of which factor is changing. Sometimes 
the end user of your appl i cati on (rather than the programmers of that 
application) needs complete flexibility in the way that they configure 
some aspect of the program. That i s, they need to do some ki nd of si mpl e 
programmi ng. The i nterpreter pattern provi des this f I exi bi I i ty by add i ng 
a language interpreter. 

The problem is that developing your own language and building an 
interpreter for it is a time-consuming distraction from the process of 
building your application. You must ask whether you want to finish 
writing your application orcreateanew language. The best solution isto 
reuse code: embed an interpreter that's already been built and debugged 
for you. The Python language can be freely embedded in your for-profit 
application without signing any license agreement, paying royalties, or 
dealing with strings of any kind. There are basically no restrictions at all 
when you're using Python. 

Python is a language that is very easy to learn, very logical to read and 
write, supports functions and objects, has a I arge set of available libraries, 
and runs on virtually every platform. You can download Python and 
learn more about it by going to www.Python.org. 

For solving Java problems, we will look at a special version of Python 
called Jython. This is generated entirely injava byte codes, so 
incorporating it into your application is quite simple, and it's as portable 
as Java is. It has an extremely clean interface with Java: Java can call 
Python classes, and Python can call Java classes. 



Python is designed with classes from the ground up and is a truly pure 
object oriented language (both C++ and Java violate purity in various 
ways). Python scales up so that you can create very big programs with it, 
without I osi ng control of the code. 



To install Python, goto |www,Python.orq|and follow the links and 
instructions. To install Jvthon, go to http://sourceforqe.net/proiects/iython 



Thedownload is a .class file, which will run an installer when you 
execute it with Java. 



Python overview 

To get you started, here is a brief introduction for the experienced 
programmer (which is what you should be if you're reading this book). 
You should refer to the full documentation atwww.Python.org (especially 
the incredibly useful HTML page A Python Quick Reference), and also 
numerous books such as Learning Python byMarkLutz and David Ascher 
(O'Reilly, 1999). 

Python is often referred to as a scripting language, but scripting 
languages tend to belimiting, especially in the scope of the problems that 
they solve. Python, on the other hand, is a programming language that 
also supports scripting. It is marvelous for scripting, and you may find 
yourself replacing all your batch files, shell scripts, and simple programs 
with Python scripts. But it isfar more than a scripting language. 

Python is designed to be very clean to write and especially to read. You 
will find that it's quite easy to read your own code long after you've 
written it, and also to read other people's code. This is accomplished 
partially through clean, to-the-point syntax, but a major factor in code 
readability is the indentation - scoping in Python is determined by 
indentation. For example: 

#: c09:if.py 

response = "yes" 

if response == "yes": 

print "affirmative" 

val = 1 
print "continuing. . . " 
#:~ 



First notice that the basic syntax of Python is C-ish, for example, the if 
statement. But in a C if, you would be required to use parentheses 
around the conditional, whereas they are not necessary in Python (but it 
won't complain if you use them anyway). 

The conditional clause ends with a colon, and this indicates that what 
followswill bea group of indented statements, which are the "then" part 
of the if statement. I n this case, there is a "pri nt" statement which sends 
the result to standard output, followed by an assignment to a variable 
named val. The subsequent statement is not indented so it is no longer 
part of the if. Indenting can nest to any level, just I ike curly braces in C++ 
orjava, butunlikethoselanguagesthereisno option (and no argument) 
about where the braces are placed - the compi I er forces everyone's code 
to be formatted thesameway, which is one of the main reasons for 
Python's consistent readability. 

Python normally has only one statement per line (you can put more by 
separating them with semicolons) and so no terminating semicolon is 
necessary. Even from this brief example you can see that the language is 
designed to be as simple as possible, and yet still very readable. 

Built-in containers 

With languages I ike C++ and Java, containers are add-on libraries and 
notintegral to the language. In Python, the essential nature of containers 
for programming is acknowledged by building them into the core of the 
language: both lists and associ ative arrays (a.k.a. maps, dictionaries, hash 
tables) are fundamental datatypes. This adds much to the elegance of the 
language. 

In addition, the for statement automatically iterates through lists rather 
than just counti ng through a sequence of numbers. This makes a lot of 
sense when you thi nk about it, si nee you're al most always usi ng a for 
loop to step through an array or a container. Python formalizes this by 
automatically making for use an iterator that works through a sequence. 
For example: 

#: c09:list.py 

list = [ 1, 3, 5, 7, 9, 11] 

print list 

list . append ( 13 ) 



for x in list: 

print x 
#:~ 

The first line creates a list. You can print the list and itwill look exactly as 
you put it i n (remember that I had to create a sped al A rrays2 cl ass i n 
ord er to p r i nt arrays i n J ava) . L i sts are I i ke J ava contai n ers - y ou can ad d 
new elements to them (here, append ( ) is used) and they will 
automatically resize themselves. The for statement creates an iterator x 
which takes on each value in the list as it prints it. 

You can create a I ist of numbers with the range( ) function, so if you 
really need to imitateC'sfor, you can. 

N oticethat there aren't any type declarations - the object names si mply 
appear, and Python infers their type. Again, it's almost as if it's created so 
that you only need to press the keys that absolutely must. You'll find 
after you've worked with Python for a short whilethat you've been using 
up a lot of brain cycles parsing semicolons, curly braces, and all sorts of 
other extra verbiage that was demanded by the programming language 
but didn't actually describe what your program was supposed to do. 

Functions 

To create a function in Python, you usethedef keyword, followed by the 
function name and argument list, and a colon to begin the function body. 
H ere i s the f i rst exampl e tu rned i nto a f u ncti on: 

#: cO 9 : myFunction . py 
def myFunction (response) : 
val = 

if response == "yes": 

print "affirmative" 

val = 1 
print "continuing. . . " 
return val 

print myFunction (' no ' ) 
print myFunction (' yes ' ) 
# : ~ 

Notice there is no type information in the function signature- all it 
specifies is the name of the function and the argument identifiers, but no 



argument types or return types. Python is a weakly-typed language, which 
means it puts the minimum possible requirements on typing. For 
example, you could pass and return different types from the same 
function: 

#: cO 9 : dif f erentReturns . py 
def dif f erentReturns (arg) : 
if arg == 1: 

return "one" 
if arg == "one " : 
return 1 

print dif f erentReturns (1 ) 
print dif f erentReturns ( "one" ) 
#:~ 

The only constraints on an object that is passed into the function are that 
the function can apply its operations to that object, but other than that, it 
doesn't care. H ere, the same function applies the '+' operator to integers 
and strings: 

#: c09:sum.py 
def sum(argl, arg2 ) : 
return argl + arg2 

print sum(42, 47) 

print sum (' spam ', "eggs") 

# : ~ 

When the operator '+' is used with strings, it means concatenation (yes, 
Python supports operator overloading, and it does a nicejob of it). 

Strings 

The above example also shows a little bit about Python string handling, 
which isthebestof any language I've seen. You can use si ngleor double 
quotes to represent strings, which isvery nice because if you surround a 
string with doublequotes, you can embed single quotes and vice versa: 

#: cO 9 : strings . py 
print "That isn't a horse" 
print 'You are not a "Viking"' 
print """You're just pounding two 
coconut halves together.""" 



print '''"Oh no!" He exclaimed. 
"It's the blemange ! " ' ' ' 
print r ' c : \python\lib\utils ' 
#:~ 

N ote that Python was not named after the snake, but rather the M onty 
Python comedy troupe, and so examples are virtually required to include 
Python-esque references. 

The triple-quote syntax quotes everything, including newlines. This 
makes it particularly useful for doing things I ike generating web pages 
(Python is an especially good CGI language), since you can just triple- 
quote the entire page that you want without any other editing. 

The'r' right beforeastring means "raw," which takes the backslashes 
literally so you don't haveto put in an extra backslash. 

Substitution in strings is exceptionally easy, since Python usesC's 
printf ( ) substitution syntax, but for any string at all. You simply follow 
thestring with a '%' and the values to substitute: 

#: cO 9 : stringFormatting . py 
val = 47 

print "The number is %d" % val 
val2 = 63.4 

s = "val: %d, val2 : %f" % (val, val2) 

print s 

#:~ 

As you can see i n the second case, if you have more than one argument 
you surround them in parentheses (this forms a tuple, which is a list that 
cannot be modified). 

All the formatting from printf ( ) isavailable, including control over the 
number of decimal places and alignment. Python also has very 
sophisticated regular expressions. 

Classes 

Like everything else in Python, thedefinition of a class uses a minimum 
of additional syntax. You use the class keyword, and insidethe body you 
usedef to create methods. H ere's a simple class (The '#' denotes a 
comment that goes until the end of the line, just I ike C++ and Java 'If 
comments): 



#: cO 9 : SimpleClass . py 
class Simple: 

def init (self, str) : 

print "Inside the Simple constructor" 
self.s = str 

# Two methods : 
def show (self) : 

print self.s 
def showMsg ( self , msg) : 
print msg + ' : ' , 

self.show() # Calling another method 

if name == " main " : 

# Create an object: 

x = Simple (" constructor argument") 
x . show ( ) 

x.showMsg("A message") 
# : ~ 

Both methods have "self" as their first argument. C-H-andJava both 
have a hidden first argument in their class methods, which points to the 
object that the method was cal I ed for and can be accessed usi ng the 
keyword this. Python methods also use a reference to the current object, 
butwhen you aredefining amethod you must explicitly specify the 
reference as the first argument. Traditionally, the reference is called self 
but you could use any identifier you want (if you do not use self you will 
probably confusea lot of people, however). If you need to refer to fields 
in the object or other methods in the object, you must use self in the 
expressi on. H owever, when you cal I a method for an object as i n 
x.show( ), you do not hand it the reference to the object - that is done for 
you. 

Here, the first method is special, as is any identifier that begins and ends 
with double underscores. In this case, it defines the constructor, which is 
automati cal I y cal I ed w hen the object i s created , j ust I i ke i n C ++ and J ava. 
H owever, at the bottom of the exampl e you can see that the creati on of an 
object looksjust likeafunction call using the class name. Python'sspare 
syntax makes you realize that the new keyword isn't really necessary in 
C++ or J ava, either. 

All the code at the bottom is set off by an if clause, which checks to see if 
something called __name__ is equivalent to __main__. Again, thedouble 
underscores indicate special names. The reason fortheif isthatthisfile 



can also be used as a library module within another program (modules 
are described shortly). In that case, you just want the classes defined, but 
you don't want the code at the bottom of the fi le to be executed. This 
parti cu I ar i f statement isonlytruewhenyouare running thisfile 
directly; that is, if you say on the command line: 

Python SimpleClass . py 

However, if this file is imported as a module into another program, the 
main code is not executed. 

Somethi ng that's a I i ttl e su rpri si ng at f i rst i s that you definefieldsinside 
methods, and notoutsideof the methods likeC++orJava (if you create 
f i el d s a I a C ++ or J ava, they implicitly become stati c f i el d s) . To create an 
object field, you just name it inside of one of the methods (usually in the 
constructor, but not always), and space is created when that method is 
ru n . Thi s seems a I i ttl e strange comi ng from C ++ or J ava w here you must 
decide ahead of time how much space your object is going to occupy, but 
itturnsoutto bea very flexibleway to program. 

I inheritance 

Because Python is weakly typed, it doesn't really care about interfaces - 
all it cares about is applying operations to objects (in fact, Java's interface 
keyword would bewasted in Python). This means that inheritancein 
Python is different from inheritancein C-f+orJava, where you often 
inheritsimply to establish a common interface. In Python, the only 
reason you inherit is to inherit an implementation - to re-use the code in 
the base class. 

If you're goi ng to inherit from a cl ass, you must tel I Python to bri ng that 
class into your new file. Python controls its namespaces as aggressively 
asjavadoes, and in a similar fashion (albeit with Python's penchant for 
simplicity). Every time you create a file, you implicitly create a module 
(which is I ike a package in J ava) with the same name as that file. Thus, no 
package keyword is needed in Python. When you want to usea module, 
you just say import and givethe name of the module. Python searches 
the PYTH ON PATH i n the same way that J ava searches the C LA SSPATH 
(but for some reason, Python doesn't havethesame kinds of pitfalls as 
Java does) and reads in thefile. To refer to any of the functions or classes 
within a module, you givethe module name, a period, and the function 



or class name. If you don't want the trouble of qualifying the name, you 
can say 

from module import name(s) 

Where "name(s)" can be a list of names separated by commas. 

You inherit a class (or classes - Python supports multiple inheritance) by 
I i sti ng the name(s) of the cl ass i nsi de parentheses after the cl ass name. 
Note that theSimple class, which residesin thefile(and thus, module) 
named SimpleC lass is brought into this new namespace using an 
import statement: 

#: c09 : Simple2 .py 

from SimpleClass import Simple 

class Simple2 (Simple) : 

def init (self, str) : 

print "Inside Simple2 constructor" 

# You must explicitly call 

# the base-class constructor: 
Simple. init (self, str) 

def display ( self ) : 

self . showMsg ( "Called from display ()") 
# Overriding a base-class method 
def show (self) : 

print "Overridden show ( ) method" 

# Calling a base-class method from inside 

# the overridden method: 
Simple . show ( self ) 

class Different: 
def show (self) : 

print "Not derived from Simple" 

if name == " main " : 

x = Simple2 ( "Simple2 constructor argument") 
x . display ( ) 
x . show ( ) 

x . showMsg (" Inside main") 

def f (obj) : obj.show() # One-line definition 
f(x) 

f (Different ( ) ) 
#:~ 



Simple2 is inherited from Simple, and in the constructor, the base-class 
constructor is called. Notethatin display( ), showMsgOcan be called as 
amethod of self, butwhen calling the base-class version of the method 
you are overriding, you must fully qualify the name and pass self in as 
the first argument, as shown in the base- class constructor call. This can 
also be seen in the overridden version of show( ). 

In __main__, you will see(when you run the program) that the base- class 
constructor is called. You can also see that the show Msg( ) method is 
availablein thederived class, just as you would expectwith inheritance. 

The class Different also has a method named show(), but this class is not 
derived from Simple. Thef( ) method defined in__main__ demonstrates 
weak typing: all it cares about isthatshow( ) can be applied toobj, and it 
doesn't have any other type requirements. You can see that f( ) can be 
applied equally to an object of a class derived from Simple and one that 
isn't, without discrimination. If you're a C-H-programmer, you should 
see that the objective of the C++ tern pi ate feature is exactly thi s: to 
provide weak typing in a strongly-typed language. Thus, in Python you 
automatically get the equivalent of templates - without having to learn 
that particularly difficult syntax and semantics. 

Creating a language 

It turns out to be remarkably simple to usejython to create an interpreted 
language inside your application. Consider the greenhouse controller 
example from Chapter 8 of Thinking in Java, 2 nd edition. This is a situation 
where you want the end user - the person managing the greenhouse -to 
have configuration control over the system, and so a simple scripting 
language is the ideal solution. 

To create the language, we'll simply write a set of Python classes, and the 
constructor of each will add itself to a master list. The common data and 
behavior will be factored into the base-class Event. Each Event object will 
contain an action string (for simplicity - in reality, you'd havesomesort 
of functional ity) and a ti me when the event is supposed to run. The 
constructor initializes these fields, and then adds the new Event object to 
astatic list called events (defining it in the class, but outside of any 
methods, is what makes it static): 



: cO 9 : GreenHouseLanguage . py 



lass Event: 
events = [] # static 
clef init (self, action, time): 

self.action = action 

self. time = time 

Event . events . append (self) 

# Used by sort() . This will cause 

# comparisons to be based only on time: 
def cmp (self, other) : 

if self. time < other. time: return -1 
if self. time > other. time: return 1 
return 
def run (self) : 

print "%.2f: %s" % (self. time, self. action) 

lass LightOn (Event ) : 

def init (self, time) : 

Event. init (self, "Light on", time) 

lass LightOff (Event) : 

def init (self, time) : 

Event. init (self, "Light off", time) 

lass WaterOn (Event ) : 

def init (self, time) : 

Event. init (self, "Water on", time) 

lass WaterOff (Event) : 

def init (self, time) : 

Event. init (self, "Water off", time) 

lass ThermostatNight (Event) : 

def init (self, time) : 

Event. init (self, "Thermostat night", time) 

lass ThermostatDay (Event ) : 

def init (self, time) : 

Event. init (self, "Thermostat day", time) 

lass Bell (Event) : 

def init (self, time) : 

Event. init (self, "Ring bell", time) 



def run ( ) : 

Event . events . sort ( ) ; 
for e in Event . events : 
e . run ( ) 

# To test, this will be run when you say: 

# python GreenHouseLanguage . py 
if name == " main " : 

ThermostatNight (5.00) 
LightOf f (2.00) 
WaterOn (3. 30) 
WaterOf f (4.45) 
LightOn (1.00) 
ThermostatDay (6.00) 
Bell (7.00) 
run ( ) 
#:~ 

The constructor of each derived class callsthe base-class constructor, 
which adds the new object to the list. The run( ) function sorts the list, 
which automatically usesthe__cmp__( ) method that was defined in 
Event to base comparisons on time only. In this example, it only prints 
out the list, but in the real system it would wait for the time of each event 
to come up and then run the event. 

The mai n secti on tests the cl asses to make sure they work ri ght. 

Theabovefileisnow a module that can be included in another Python 
program to def i ne al I the cl asses it contai ns. But i nstead of an ordi nary 
Python program, let'susejython inside of Java. This turns out to be 
remarkably simple: you import some J ython classes, create a 
Python Interpreter object, and causethefilesto beloaded in: 

//: c09:GreenHouseCont roller. java 
import org . python . util . Pythonlnterpreter; 
import org . python . core . * ; 
import com . bruceeckel . test .* ; 

public class 

GreenHouseController extends UnitTest { 
Pythonlnterpreter interp = 
new Pythonlnterpreter () ; 
public void test() throws PyException { 



System. out .print In ( 

"Loading GreenHouse Language"); 
interp . execf ile ( "GreenHouseLanguage . py " ) ; 
System. out .print In ( 

"Loading GreenHouse Script"); 
interp . execf ile ( "Schedule . ghs " ) ; 
System. out .print In ( 

"Executing GreenHouse Script"); 
interp . exec ( "run ( ) " ) ; 

} 

public static void 

main (String [ ] args) throws PyException { 
new GreenHouseController () .test () ; 

} 

} ///:- 

The Python I interpreter object is a complete Python i interpreter that 
accepts commands from tnej ava program. One of these commands is 
execf i I e( ), whi ch tel I s i t to execute al I the statements i t f i nds i n a 
particular file. By executing Green HouseLanguage.py, all the classes 
from that file are loaded into our Python Interpreter object, and so it now 
"holds" the greenhouse controller language. The Schedule.ghs file is the 
one created by the end user to control the greenhouse. H ere's an 
example: 

//:! c09 : Schedule . ghs 
Bell (7.00) 
ThermostatDay (6.00) 
WaterOn (3. 30) 
LightOn (1.00) 
ThermostatNight (5.00) 
LightOf f (2.00) 
WaterOf f (4.45) 
///:- 

This is the goal of the interpreter design pattern: to make the 
configuration of your program as simple as possible for the end user. 
Withjython you can achieve this with almost no effort at al I . 

One of the other methods avail able to the Python Interpreter isexec( ), 

which allows you to send a command to the interpreter. Here, therun( ) 
function is called using exec( ). 



Configuring J ython 



Remember, to run this program yo u must go to 
|http://sourceforqe.net/proiects/iython] and download and install Jython 



(actually, you only need jython .jar in your CLASSPATH). Once that's in 
place, it's just like running any other Java program. 

You may need to editjython.bat, as it can incorrectly assume a path for 
yourjava.exe program. 

Many improvements have been made in the installation process for 
Jython over the old J Python, but it's still important that jython .jar is in 
your CLASSPATH. 



Generating documentation 

Jython 2.0, for some reason, is distributed with only minimal API 
documentation. In fact, only Python Interpreter hasthejava 
documentation created for it. Thejava documentation strings are there 
for the rest of the classes, but they weren't extracted. Although many of 
the classes are not necessary in order to program with Jython, many are 
and so it's valuable to run Javadoc in order to generate the HTM L 
documentation. 

Here is the makefile that I used to create thejava documentation: 

all: 

javadoc -sourcepath C:\Progtools\Jython\ \ 
-d C:\ProgTools\Jython\docs\new \ 
org . python . core org . python . modules \ 
org . python . util org . python . rmi 

You'll have to adjust the paths to fit your own installation. The 
sourcepath iswhereyou installed Jython, and -d indicates the 
destination directory for the generated HTML files. Look uptheJDK 
online documentation for Javadoc for further details. 

Once you generate the documentation, you can pokethrough and pick 
up a few bits and pieces you wouldn't otherwise find. 



Controlling the interpreter 

The prior exampleonly creates and runs the interpreter using external 
scripts. In the rest of this chapter, we shall look at more sophisticated 
ways to i nteract with Jython. The simplest way to have more control over 
the Python I interpreter object from withi n J ava is to send data to the 
interpreter, and pull data back out. 

Putting data in 

To inject data into your Python program, the Python Interpreter class has 
a deceptively simple method: set( ). H owever, set( ) takes many different 
datatypesand performs conversions upon them. The foil owing example 
is a reasonably thorough exerci se of the various set( ) possibilities, along 
with comments that should giveafairly complete explanation: 

// : cO 9 : PythonlnterpreterSetting . java 

// Passing data from Java to python when using 

// the Pythonlnterpreter object. 

import org . python . util . Pythonlnterpreter ; 

import org . python . core . * ; 

import java . util . * ; 

import com . bruceeckel . python . * ; 

import com . bruceeckel . test .* ; 

public class 

PythonlnterpreterSetting extends UnitTest { 
Pythonlnterpreter interp = 
new Pythonlnterpreter () ; 
public void test() throws PyException { 
// It automatically converts Strings into 
// native Python strings: 
interp . set ( "a" , "This is a test"); 
interp . exec ( "print a"); 

interp . exec ( "print a[5:]"); // A slice 
// It also knows what to do with arrays: 
String [] s = { "How", "Do", "You", "Do?" }; 
interp . set ( "b" , s) ; 

interp . exec (" for x in b: print x[0], x"); 
// set() only takes Objects, so it can't 
// figure out primitives. Instead, 
// you have to use wrappers: 



interp . set ( "c" , new Pylnteger ( 1 ) ) ; 
interp . set ( "d" , new PyFloat (2 . 2 ) ) ; 
interp . exec ( "print c + d"); 

// You can also use Java's object wrappers: 
interp . set ( "c" , new Integer (9)); 
interp. set ("d", new Float (3 . 14 ) ) ; 
interp . exec ( "print c + d"); 

// Define a Python function to print arrays: 

interp . exec ( 

"def prt (x) : \n" + 

" print x \n" + 

" for i in x: \n" + 

" print i, \n" + 

" print x. class \n"); 

// Arrays are Objects, so it has no trouble 

// figuring out the types contained in arrays 

Object [] types = { 

new boolean[]{ true, false, false, true }, 

new char[] { 'a', 'b\ 'c\ 'd' }, 

new byte [ ] { 1, 2, 3, 4 } , 

new int [ ] { 10, 20, 30, 40 } , 

new long[]{ 100, 200, 300, 400 }, 

new float []{ l.lf, 2.2f, 3.3f, 4.4f }, 

new doublet] { 1.1, 2.2, 3.3, 4.4 }, 

}; 

for (int i = 0; i < types . length; i++) { 
interp . set ( "e" , types [i]); 
interp . exec ( "prt (e ) " ) ; 

} 

// It uses toStringO to print Java objects: 

interp . set (" f" , new DateO); 

interp . exec ( "print f"); 

// You can pass it a List and 

// index into it . . . 

ArrayList x = new ArrayList () ; 

for (int i = 0; i < 10; i++) 

x.add(new Integer (i * 10)); 
interp . set ( "g" , x) ; 
interp . exec ( "print g"); 
interp . exec ( "print g[l]"); 
// ... But it's not quite smart enough 
// to treat it as a Python array: 

interp . exec ( "print g . class " ) ; 

// interp . exec ( "print g[5:]); // Fails 



// If you want it to be a python array, you 
// must extract the Java array: 
System. out .println ( "ArrayList to array: ") ; 
interp . set ( "h" , x . toArray ( ) ) ; 

interp . exec ( "print h . class " ) ; 

interp . exec ( "print h[5:]"); 
// Passing in a Map: 
Map m = new HashMapO; 

m. put (new Integer (1), new Character (' a ')) ; 
m. put (new Integer (3), new Character (' b ')) ; 
m. put (new Integer (5), new Character (' c ')) ; 
m. put (new Integer (7), new Character (' d ')) ; 
m. put (new Integer (11), new Character (' e ')) ; 
System. out .println ( "m: " + m) ; 
interp . set ( "m" , m) ; 

interp . exec ( "print m, m. class , " + 

"m[l], m[l] . class "); 

// Not a Python dictionary, so this fails: 
// ! interp . exec (" for x in m.keys():" + 
// ! "print x, m[x] ") ; 

// To convert a Map to a Python dictionary, 
// use com . bruceeckel . python . PyUtil : 
interp . set ( "m" , PyUtil . toPyDictionary (m) ) ; 

interp . exec ( "print m, m. class , " + 

"m[l], m[l] . class "); 

interp . exec (" for x in m. keys (): print x,m[x]"); 

} 

public static void 

main (String [ ] args) throws PyException { 
new PythonlnterpreterSetting ( ) .test () ; 

} 

} ///:~ 

Asusual withjava, the distinction between real objects and primitive 
types causes trouble. In general, if you pass a regular object to set( ), it 
knows what to do with it, but if you want to pass in a primitive you must 
perform a conversion. Oneway to do this is to create a "Py" type, such as 
Pylnteger or PyFloat. but itturns out you can also usejava's own object 
wrappers I ike Integer and Float, which is probably going to be a lot 
easier to remember. 



Early in the program you'll see an exec( ) containing the Python 
statement: 



print a [ 5 : ] 

The colon inside the indexing statement indicates a Python slice, which 
produces a range of dements from the original array. In this case, it 
produces an array containing the elements from number 5 until the end 
of the array. You could also say 'a[3:5]' to produce elements 3 through 5, 
or 'a[:5]' to produce the elements zero through 5. The reason a slice is 
used in misstatement isto make sure that the Java String has really been 
converted to a Python string, which can also be treated as an array of 
characters. 

You can see that it's possible, using exec( ), to create a Python function 
(although it's a bit awkward). The prt( ) function prints the whole array, 
and then (to make sure it's a real Python array), iterates through each 
element of the array and prints it. Finally, it prints the class of the array, 
so we can see what conversion has taken place (Python not only has run- 
time type information, it also has the equivalent of Java reflection). The 
prt( ) function is used to print arrays that come from each of thejava 
pri mi tive types. 

Although a Java Array List does pass into the interpreter using set( ), and 
you can index into it as if it were an array, trying to create a si ice fails. To 
completely convert it into an array, one approach isto simply extract a 
Java array using toArray( ), and pass that in. Theset( ) method converts it 
toa PyArray type, which is one of the classes provided withjython and 
can be treated as a Python array (you can also explicitly create a PyArray, 
bu t th i s seems u n n ecessary ) . 

Finally, a Map iscreated and passed directly into the interpreter. Whileit 
is possible to do simple things like index into the resulting object, it's not 
a real Python dictionary so you can't (for example) call thekeys( ) 
method. There is no straightforward way to convert ajava M ap into a 
Python dictionary, and so I wrotea utility called toPyDictionary( ) and 
made it a static method of com .bruceeckel. python. PyU til . This also 
includes utilities to extract a Python array into a Java List, and a Python 
d i cti onary i nto a J ava M ap : 

// : com: bruceeckel : python : PyUtil . java 

// Pythonlnterpreter utilities 

package com. bruceeckel .python; 

import org . python . util . Pythonlnterpreter ; 

import org . python . core . * ; 



import java . util . * ; 



public class PyUtil { 

/** Extract a Python tuple or array into a Java 

List (which can be converted into other kinds 

of lists and sets inside Java) . 

Sparam interp The Python interpreter object 

@param pyName The id of the python list object 

*/ 

public static List 

toList (Pythonlnterpreter interp, String pyName) { 
return new ArrayList (Arrays . asList ( 
(Object [ ] ) interp . get ( 

pyName, Ob ject []. class) )) ; 

} 

/** Extract a Python dictionary into a Java Map 
@param interp The Python interpreter object 
@param pyName The id of the python dictionary 
*/ 

public static Map 

toMap (Pythonlnterpreter interp, String pyName) { 
PyList pa = ( (PyDictionary) interp . get ( 

pyName) ) .items () ; 
Map map = new HashMapO; 

while (pa. len () != 0) { 

PyTuple po = (PyTuple) pa . pop () ; 

Object first = po . finditem (0) 

. tojava (Ob ject . class) ; 

Object second = po . finditem (1) 

. tojava (Ob ject . class) ; 

map . put ( first, second); 

} 

return map; 

} 

/** Turn a Java Map into a PyDictionary, 
suitable for placing into a Pythonlnterpreter 
@param map The Java Map object 
*/ 

public static PyDictionary 
toPyDictionary (Map map) { 
Map m = new HashMapO; 

Iterator it = map . entrySet (). iterator () ; 
while ( it . hasNext () ) { 

Map. Entry e = (Map . Entry) it . next () ; 



m. put (Py . java2py (e . get Key ( ) ) , 
Py . java2py (e . getValue ( ) ) ) ; 

} 

// PyDictionary constructor wants a Hashtable: 
return new PyDictionary (new Hashtable (m) ) ; 

} 

} ///:- 

Here is the (black- box) unittesting code: 

// : com: bruceeckel : python: Test . java 

package com. bruceeckel .python; 

import org . python . util . Pythonlnterpreter; 

import java . util . * ; 

import com . bruceeckel . test .* ; 

public class Test extends UnitTest { 
Pythonlnterpreter pi = 

new Pythonlnterpreter () ; 
public void testl() { 

pi .exec ("tup= ( ' fee ' , ' f i ' , ' f o ' , ' fum' , ' fi ' ) ") ; 

List 1st = PyUtil.toList (pi, "tup"); 

System . out . print In (1st ) ; 

System . out . print In (new HashSet ( 1st ) ) ; 

} 

public void test2() { 

pi .exec ("ints= [1, 3, 5,7,9,11,13,17,19]"); 
List 1st = PyUtil.toList (pi, "ints"); 
System . out . print In (1st ) ; 

} 

public void test3() { 

pi. exec ("diet = { 1 : 'a', 3 : 'b', " + 
"5 : ' c ' , 9 : ' d ' , 11 : ' e ' } " ) ; 

Map mp = PyUtil . toMap (pi, "diet"); 
System . out . print In (mp) ; 

} 

public void test4() { 
Map m = new HashMapO; 
m. put ( "twas " , new Integer (11 )) ; 
m. put ( "brillig" , new Integer (27 )) ; 
m. put ("and", new Integer (47 )) ; 
m. put ("the", new Integer ( 42 )) ; 
m. put ( " slithy " , new Integer (33) ) ; 
m. put ( "toves " , new Integer ( 55 )) ; 
System . out . print In (m) ; 



pi . set ( "m" , PyUtil . toPyDictionary (m) ) ; 

pi . exec ( "print m"); 

pi . exec ( "print m [ ' slithy ' ] " ) ; 

} 

public static void main (String args [ ] ) { 
Test t = new Test ( ) ; 
t.testl () ; 
t.test2 () ; 
t. test 3 () ; 
t. test 4 () ; 

} 

} ///:- 

We' 1 1 see the use of the extracti on tool s i n the next secti on . 

Getting data out 

There are a number of different ways to extract data from the 
Python Interpreter. If you simply call theget( ) method, passing itthe 
object identifier as a string, it returns a PyO bject (part of the 
org.python.core support classes). It's possibleto "cast" it using the 
toj ava ( ) method, but there are better alternatives: 

1. The convenience methods in thePy class, such as py2int( ), take a 
PyO bject and convert it to a number of different types. 

2 . An overl oaded versi on of get( ) takes the desi red J ava C I ass object 
as a second argument, and produces an object that has that run- 

ti me type (so you still need to cast the result). 

Using the second approach, getting an array from the Python Interpreter 

isquiteeasy. This is especially useful because Python is exceptionally 
good at manipulating strings and files, and so you will commonly want 
to extract the results as an array of strings. For example, you can do a 
wildcard expansion of file names using Python'sglob( ), as shown 
further down in thefollowing code: 

// : cO 9 : PythonlnterpreterGetting . java 

// Getting data from the Pythonlnterpreter object. 

import org . python . util . Pythonlnterpreter; 

import org . python . core . * ; 

import java . util . * ; 

import com . bruceeckel . python . * ; 



import com . bruceeckel . test .* ; 
public class 

PythonlnterpreterGetting extends UnitTest{ 
Pythonlnterpreter interp = 

new Pythonlnterpreter () ; 
public void test() throws PyException { 

interp . exec ( "a = 100"); 

// If you just use the ordinary get ( ) , 
// it returns a PyObject: 
PyObject a = interp . get ( "a" ) ; 

// There's not much you can do with a generic 
// PyObject, but you can print it out: 
System. out .println ( "a = " + a); 
// If you know the type it's supposed to be, 

// you can "cast" it using tojava () to 

// that Java type and manipulate it in Java. 
// To use 'a' as an int, you must use 
// the Integer wrapper class: 

int ai= ((Integer) a. tojava (Integer . class) ) 

. int Value ( ) ; 
// There are also convenience functions: 
ai = Py . py2int (a) ; 

System. out .println ( "ai + 47 = " + (ai + 47)); 
// You can also choose to convert 
// it to different types: 
float af = Py .py2f loat (a) ; 

System. out .println ("af + 47 = " + (af + 47)); 
// If you try to cast it to an inappropriate 
// type you'll get a runtime exception: 

III String as = (String) a. tojava ( 

III String . class ) ; 

// If you know the type, a more useful method 
// is the overloaded get ( ) that takes the 
// desired class as the 2nd argument: 
interp . exec ( "x = 1 + 2"); 
int x = (( Integer ) interp 

. get ( "x" , Integer . class )) . int Value ( ) ; 
System. out .println ( "x = " + x) ; 

// Since Python is so good at manipulating 
// strings and files, you will often need to 
// extract an array of Strings. Here, a file 



// is read as a Python array: 
interp . exec ( "lines = " + 

"open ( ' PythonlnterpreterGetting . java ' ) " + 

" . readlines ( ) " ) ; 
// Pull it in as a Java array of String: 
String [] lines = (String[]) 

interp . get (" lines " , String [ ] .class ) ; 
for(int i = 0; i < 10; i++) 

System. out .print (lines [i] ) ; 

// As an example of useful string tools, 

// global expansion of ambiguous file names 

// using glob is very useful, but it's not 

// part of the standard Jython package, so 

// you'll have to make sure that your 

// Python path is set to include these, or 

// that you deliver the necessary Python 

// files with your application. 

interp . exec (" from glob import glob"); 

interp . exec (" files = glob ('*. java ')") ; 

String [] files = (StringH) 

interp . get (" files " , String [ ] .class ) ; 
for(int i = 0; i < files . length; i++) 

System . out .print In (files [i] ) ; 

// You can extract tuples and arrays into 
// Java Lists with com . bruceeckel . PyUtil : 
interp . exec ( 

"tup = ('fee', 'fi', 'fo', 'fum', 'fi')"); 
List tup = PyUtil . toList (interp, "tup"); 
System. out .print In (tup) ; 

// It really is a list of String objects: 
System . out . print In (tup . get ( ) . get CI ass ( ) ) ; 
// You can easily convert it to a Set: 
Set tups = new HashSet (tup) ; 
System. out .print In (tups) ; 

interp. exec ("ints= [1, 3,5,7,9,11,13,17,19]"); 
List ints = PyUtil . toList (interp, "ints"); 
System. out .print In (ints) ; 

// It really is a List of Integer objects: 
System . out .print In ((ints. get ( 1 ) ) . get Class ( ) ) 

// If you have a Python dictionary, it can 
// be extracted into a Java Map, again with 



// com . bruceeckel . PyUtil : 

interp . exec ( "diet = { 1 : 'a', 3 : 'b'," + 
"5 : ' c ' , 9 : ' d ' , 11 : ' e ' } " ) ; 

Map map = PyUtil . toMap (interp, "diet"); 
System . out . print In ( "map : " + map); 
// It really is Java objects, not PyObjects: 
Iterator it = map . entrySet (). iterator () ; 
Map. Entry e = (Map .Entry) it . next () ; 
System. out .print In (e . get Key ( ) . get CI ass ( ) ) ; 
System. out .print In (e . get Value ( ) . get CI ass ( ) ) ; 

} 

public static void 

main (String [ ] args) throws PyException { 
new PythonlnterpreterGetting ( ) .test () ; 

} 

} ///:- 

The I ast two exampl es show the extracti on of Python tu pi es and I i sts i nto 
Java Lists, and Python dictionaries into Java M aps. Both of these cases 
require more processing than is provided in the standard J ython library, 
so I haveagain created utilities in com.bruceeckel.pyton. PyUtil: toList( ) 
to produce a List from a Python sequence, and toM ap( ) to produce a 
M ap from a Python dictionary. The PyUtil methods make it easier to take 
important data structures back and forth between J ava and Python. 

Multiple interpreters 

It'salso worth noting that you can have multiple Python Interpreter 

objects in a program, and each one has its own namespace: 

//: cO 9 : Multiple Jythons . java 

// You can run multiple interpreters, each 

// with its own name space. 

import org . python . util . Pythonlnterpreter; 

import org . python . core . * ; 

import com . bruceeckel . test .* ; 

public class Multiple Jythons extends UnitTest { 
Pythonlnterpreter 

interpl = new Pythonlnterpreter () , 

interp2 = new Pythonlnterpreter () ; 
public void test() throws PyException { 

interpl . set ( "a" , new Pylnteger ( 42 )) ; 

interp2 . set ( "a" , new Pylnteger ( 47 )) ; 



interpl . exec ( "print a"); 

interp2 . exec ( "print a"); 

PyObject xl = interpl . get ( "a" ) ; 

PyObject x2 = interp2 . get ( "a" ) ; 

System. out .println ( "a from interpl: " + xl); 

System. out .println ( "a from interp2 : " + x2); 

} 

public static void 

main (String [ ] args) throws PyException { 
new Multiple Jythons (). test () ; 

} 

} lll'.~ 

When you run the program you'll see that the value of a is distinct within 
each Python Interpreter. 

Controlling J ava from 
J ython 

Since you havethejava language at your disposal, and you can set and 
retr i evevaluesintheinterp reter , th ere' s a tr emen dousamountthatyou 
can accomplish with the above approach (controlling Python fromjava). 
But one of the amazi ng thi ngs about J ython i s that it makes J ava cl asses 
almost transparently avail able from within J ython. Basically, a J ava class 
looks like a Python class. This is true for standard Java library classes and 
classes that you create yourself, as you can see here: 

#: c09 : JavaClassInPython .py 
#=M jython JavaClassInPython .py 

# Using Java classes within Jython 

from java.util import Date, HashSet, HashMap 
from c09 . javaclass import JavaClass 
from math import sin 

d = Date() # Creating a Java Date object 
print d # Calls toStringO 

# A "generator" to easily create data: 
class ValGen: 

def init (self, maxVal) : 

self.val = range (maxVal ) 



# Called during 'for' iteration: 
def getitem (self, i) : 

# Returns a tuple of two elements: 

return self.val[i], sin ( self . val [ i ] ) 

# Java standard containers: 
map = HashMapO 

set = HashSet ( ) 

for x, y in ValGen(lO) : 
map . put (x, y ) 
set . add (y ) 
set . add (y ) 

print map 
print set 

# Iterating through a set: 
for z in set : 

print z, z. class 

print map [3] # Uses Python dictionary indexing 
for x in map . keySet ( ) : # keySet() is a Map method 
print x, map [x] 

# Using a Java class that you create yourself is 

# just as easy: 
jc = JavaClass ( ) 

jc2 = JavaClass ( "Created within Jython") 
print jc2 . getVal ( ) 

jc . setVal ( "Using a Java class is trivial") 

print jc.getVal() 

print jc . getChars ( ) 

jc.val = "Using bean properties" 

print jc.val 

# : ~ 

The "=M " comment is recognized by the makefile generator tool (that I 
created for this book) as a replacement makefi le command. This wi 1 1 be 
used instead of the commands that the extraction tool would normally 
pi ace in the makefile. 

N ote that the i mport statements map to thej ava package structure 
exactly as you would expect. I n thefirst example, a D ate( ) object is 



created as if it were a native Python class, and printing this object just 
callstoString( ). 

ValGen implements the concept of a "generator" which is used a great 
deal in the C++ STL (Standard Template Library, part of the Standard C++ 
Library). A generator is an object that produces a new object every time 
its "generation method" iscalled.and it is quite convenient for filling 
containers. Here, I wanted to use it in afor iteration, and so I needed the 
generation method to be the one that is called by the iteration process. 
This is a special method called __getitem__( ), which is actually the 
overloaded operator for indexing, '[ ]'. A for loop calls this method every 
time it wants to move the iteration forward, and when the elements run 
out, __getitem__( ) throws an out-of-bounds exception and that signals 
the end of thefor loop (in other languages, you would never use an 
exception for ordinary control flow, but in Python it seems to work quite 
well). This exception happens automatically when self.val[i] runs out of 
elements, sothe__getitem__( ) codeturns out to be simple. The only 
complexity isthat__getitem__( ) appears to return two objects instead of 
just one. What Python does is automatically package multiple return 
values into a tuple, so you still only end up returning a single object (in 
C ++ or J ava y ou w ou I d h ave to create you r ow n d ata str u ctu re to 
accomplish this). In addition, in thefor loop whereValGen is used, 
Python automatically "unpacks" the tuple so that you can havemultiple 
iterators i n the for. These are the ki nds of syntax si mpl if i cati ons that 
make Python so endeari ng. 

The map and set objects are instances of Java's H ashM ap and H ashSet, 
again created as if those classes werejust native Python components. In 
thefor loop, theput( ) and add( ) methods work just likethey do in Java. 
Also, indexing into ajava Map uses the same notation as for dictionaries, 
but note that to iterate through the keys in a M ap you must use the M ap 
method keySet( ) rather than the Python dictionary method keys( ). 

The f i nal part of the exampl e shows the use of a J ava cl ass that I created 
from scratch, to demonstrate how trivial it is. N otice also that Jython 
intuitively understands J avaBeans properties, since you can either use the 
getVal( ) and setVal( ) methods, or assign to and read from the 
equivalent val property. Also, getChars( ) returns a Character!] injava, 
and this becomes an array in Python. 



The easi est way to use J ava cl asses that you create for use i nsi de a Python 
program isto put them inside a package. Although J ython can also 
import unpackaged java classes (importJavaClass), all such unpackaged 
java classes will be treated as if they were defined in different packages 
so they can only see each other's public methods. 

Java packages translate into Python modules, and Python must importa 
mod u I e i n ord er to be abl e to u se th e J ava cl ass. H ere i s th e J ava cod e f or 
JavaClass: 

//: cO 9 : javaclass : JavaClass . java 
package cO 9 . javaclass; 
import com . bruceeckel . test .* ; 
import com . bruceeckel . util .* ; 

public class JavaClass { 
private String s = ""; 
public JavaClass () { 

System . out . print In ( " JavaClass ( ) " ) ; 

} 

public JavaClass (String a) { 
s = a; 

System. out .print In ( "JavaClass (String) " ) ; 

} 

public String get Val ( ) { 

System. out .println ( "getVal ( ) " ) ; 
return s; 

} 

public void setVal (String a) { 
System . out .println ( " setVal ( ) " ) ; 
s = a; 

} 

public Character [] getChars() { 

System. out .println ( "getChars ( ) " ) ; 
Character [ ] r = new Character [ s . length ()] ; 
for(int i = 0; i < s. length (); i++) 

r[i] = new Character (s . charAt (i) ) ; 
return r; 

} 

public static class Test extends UnitTest { 
JavaClass 

xl = new JavaClass (), 

x2 = new JavaClass ( "UnitTest ") ; 
public void testl() { 



System .out. print In (x2. getVal ( ) ) ; 

xl . setVal ( "SpamEggsSausageAndSpam" ) ; 

Arrays 2 . print (xl . get Chars ( ) ) ; 

} 

} 

public static void main ( String [ ] args) { 
Test test = new Test(); 
test .testl () ; 

} 

} ///:- 

You can see that this is just an ordinaryjava class, without any awareness 
that it will be used in a Jython program. For this reason, one of the 
important uses of Jython is in testing Java code^ Because Python is such a 
powerful, flexible, dynamic language it is an ideal tool for automated test 
frameworks, without making any changes to the Java code that's being 
tested. 

Using J ava libraries 

Jython wraps the J ava I ibraries so that any of them can be used di recti y or 
via inheritance. In addition, Python allows its shorthand to be used to 
simplify coding. 

As an example, consider the HTM LButton.java examplefrom Chapter 9 
of Thinking in Java, 2 nd edition (you presumably have already downloaded 
and installed thesourcecodeforthatbookfromwww.BruceEckd.com, 
si nee a number of examples in this book use I ibraries from that book). 
Here is its conversion to Jython: 

#: cO 9 : PythonSwing . py 

# The HTMLButton . java example from 

# "Thinking in Java, 2nd edition, " Chapter 13, 

# converted into Jython. 

# Don't run this as part of the automatic make: 
#=M @echo skipping PythonSwing . py 

from javax. swing import JFrame, JButton, JLabel 



2 Changing the registry setting python .security.respectJavaAccessibility = true 

to false makes testi ng even more powerful because it allows the test script to use 
*al I* methods, even protected and package-private. 



from java.awt import FlowLayout 



frame = JFrame ( "HTMLButton" , visible=l, 

defaultCloseOperation=JFrame . EXIT_ON_CLOSE) 

def kapow (e) : 

frame . contentPane . add ( JLabel ( "<html>"+ 
"<ixfont size=+4>Kapow! ") ) 

# Force a re-layout to 

# include the new label: 
frame . validate ( ) 

button = JButton ( "<htmlxbxfont size=+2>" + 

"<center>Hello ! <br><i>Press me now!", 

actionPerf ormed=kapow) 
frame . contentPane . layout = FlowLayout () 
frame . contentPane . add (button) 
frame . pack ( ) 
frame. size=200, 500 
#:~ 

If you compare the Java version of the prog ram to the above J yth on 
implementation, you'll seethatjython isshorter and generally easier to 
understand. For example, in thejava version to set up the frame you had 
to make several calls: the constructor for JFrame( ), thesetVisible( ) 
method and thesetDefaultCloseOperation( ) method, whereas in the 
abovecodeall three of these operations are performed with asingle 
constructor call. 

Also notice that the J Button is configured with an action Listener! ) 

method inside the constructor, with the assignment to kapow. In 
additi on, Jython's J avaBean awareness means that a cal I to any method 
with a name that begins with "set" can be replaced with an assignment, 
as you can see above. 

The only method that did not come over from Java isthepack( ) method, 
which seems to be essential i n order to force the layout to happen 
properly. It's also important that the cal I to pack( ) appear beforethesize 
setting. 



I nheriting from J ava library classes 

You can easily inherit from standard Java library classes in Jyth on. Here's 
theDialogs.java examplefrom Chapter 13 of Thinking in Java, 2 nd edition, 
converted intojython: 

#: cO 9 : PythonDialogs . py 

# Dialogs. java from "Thinking in Java, 2nd 

# edition," Chapter 13, converted into Jython . 

# Don't run this as part of the automatic make: 
#=M @echo skipping PythonDialogs . py 

from java.awt import FlowLayout 

from javax. swing import JFrame, JDialog, JLabel 
from javax. swing import JButton 

class MyDialog (JDialog) : 

def init (self, parent=None) : 

JDialog. init (self, 

title="My dialog", modal=l) 
self . contentPane . layout = FlowLayout () 
self . contentPane . add (JLabel ( "A dialog ! " ) ) 
self . contentPane . add (JButton ( "OK" , 
actionPerf ormed = 

lambda e, t=self: t . dispose ()) ) 
self . pack ( ) 

frame = JFrame ( "Dialogs " , visible=l, 

def aultCloseOperation= JFrame . EXIT_ON_CLOSE) 

dig = MyDialog ( ) 

frame . contentPane . add ( 

JButton ( "Press here to get a Dialog Box", 
actionPerf ormed = lambda e: dlg.show())) 

frame . pack ( ) 

#:~ 

MyDialog is inherited fromJDialog, and you can see named arguments 
being used in the call to the base-class constructor. 

In the creation of the "OK" JButton, note that the action Performed 

method isset right inside the constructor, and that the function is created 
using the Python lambda keyword. This creates a nameless function with 
the arguments appearing before the col on and the expression that 
generates the returned valueafter the colon. Asyou should know, the 
Java prototype for the action Performed! ) method only contains a single 



argument, but the lambda expression indicates two. However, thesecond 
argument is provided with a default value, sothefunction can be called 
with only one argument. The reason for thesecond argument is seen in 
the default value, becausethisisa way to pass self into the lambda 
expression, so that it can be used to dispose of the dialog. 

Compare this code with the version that's published in Thinking in Java, 
2 nd edition. You'll find that Python language features allow a much more 
succinct and direct implementation. 

Creating Java classes with 
J ython 

Although itdoes not directly relate to the original problem of this chapter 
(creating an interpreter), J ython has the additional ability to createjava 
classes directly from yourjython code. This can produce very useful 
results, as you are then ableto treat the results as if they are nativejava 
classes, albeit with Python power under the hood. 

To producejava classes from Python codejython comes with a compiler 
called jythonc. 

The process of creating Python classes that will producejava classes is a 
bit more complex than when calling Java classes from Python, because 
the methods in Java classes are strongly typed, while Python functions 
and methods are weakly typed. Thus, you must somehow tell jythonc 
that a Python method is intended to have a particular set of argument 
types and that its return val ue is a parti cular type. You accompl ish this 
with the"@5ig" string, which isplaced right after the beginning of the 
Python method definition (this is the standard location for the Python 
documentation string). For example: 

def returnArray ( self ) : 

"@sig public java . lang . String [ ] returnArray () " 

The Python definition doesn't specify any return type, butthe@5ig string 
gives thefull type information about what is being returned. Thejythonc 
compiler uses this information to generate the correct Java code. 



There's one other set of rules you must follow in order to get a successful 
compilation: you must inherit from a Java class or interface in your 
Python class (you do not need to specify the @sig signature for methods 
which is defined in the superclass/ interface). If you do not do this, you 
won't get your desired methods - unfortunately, jythonc gives you no 
warnings or errors in this case, but you won't get what you want. If you 
don't see what's missing, it can be very frustrating. 

In addition, you must import the appropriate java class and give the 
correct package specification. In the example below, java is imported so 
you mustinheritfromjava.lang.Object, but you could also say from 
java.lang import bject and then you'd just inherit from bject without 
the package specification. Unfortunately, you don't get any warnings or 
errors if you get this wrong, so you must be patient and keep trying. 

Hereisan exampleof a Python class created to produce a Java class. This 
also introdu ces the' =T' directivefor the makefile builder tool, which 
sped f i es a d i ff er ent target th an th e on e th at i s n or mal I y used by th e tool . 
I n thi s case, the Python f i I e i s used to bu i I d a J ava .cl ass f i I e, so the cl ass 
f i I e i s th e d esi red makef i I e target. To accomp I i sh th i s, th e d ef au 1 1 makef i I e 
command is replaced using the '=M ' directive (notice how you can break 
across lines using '\ '): 

#: c09 :PythonToJavaClass .py 

#=T python \ java\ test \PythonTo JavaC lass .class 
#=M jythonc — package python . java . test \ 
#=M PythonTo JavaClass .py 

# A Python class created to produce a Java class 
from jarray import array 
import java 

class PythonTo JavaClass ( java . lang . Ob ject ) : 

# The ' @sig' signature string is used to create 

# the proper signature in the resulting 

# Java code: 

def init (self) : 

"@sig public PythonTo JavaClass () " 

print "Constructor for PythonTo JavaClass" 

def simple (self) : 

"@sig public void simple ()" 
print "simple ()" 



# Returning values to Java: 
def returnString (self ) : 

"@sig public java . lang . String returnString () " 
return "howdy" 

# You must construct arrays to return along 

# with the type of the array: 
def returnArray ( self ) : 

"@sig public java . lang . String [ ] returnArray ( ) 
test = [ "fee", "fi", "fo", "fum" ] 
return array (test, java. lang. String) 

def ints (self) : 

"@sig public java . lang . Integer [ ] ints()" 
test = [ 1, 3, 5, 7, 11, 13, 17, 19, 23 ] 
return array (test, java. lang. Integer) 

def doubles ( self ) : 

"@sig public java . lang . Double [ ] doubles ()" 
test = [ 1, 3, 5, 7, 11, 13, 17, 19, 23 ] 
return array (test, java . lang . Double ) 

# Passing arguments in from Java: 
def arglnl (self, a) : 

"@sig public void arglnl ( java . lang . String a)" 

print "a: %s" % a 

print "a. class ", a. class 

def argln2 (self, a) : 

"@sig public void arglnl ( java . lang . Integer a) 
print "a + 100: %d" % (a + 100) 
print "a. class ", a. class 

def argln3 (self, a) : 

"@sig public void argln3 ( java . util . List a)" 

print "received List:", a, a. class 

print "element type:", a[0]. class 

print "a[3] + a[5]:", a[5] + a[7] 

#! print "a[2:5]:", a[2:5] # Doesn't work 

def argln4 (self, a) : 
"@sig public void \ 

argln4 (org . python . core . PyArray a) " 
print "received type:", a. class 



print "a: ", a 

print "element type:", a[0]. class 

print "a[3] + a[5]:", a[5] + a[7] 

print "a [2: 5]:", a [2: 5] # A real Python array 

# A map must be passed in as a PyDictionary : 
clef argln5 (self, m) : 
"@sig public void \ 

argln5 (org . python . core . PyDictionary m) " 

print "received Map: ", m, m. class 

print "m[ '3' ] : ", m['3' ] 
for x in m.keys(): 
print x, m[x] 

#:~ 

First note that PythonToJavaClass is inherited from java.lang.Object; if 

you don't do this you will quietly get a Java class without the right 
signatures. You are not required to inherit from Object; any other Java 
class will do. 

This class is designed to demonstrate different arguments and return 
values, to provideyou with enough examples that you'll beableto easily 
create your own signature strings. The first three of these are fairly self- 
explanatory, but notethefull qualification of thejava name in the 
signature string. 

I n returnA rray( ), a Python array must be returned as a J ava array. To do 
this, thejython array( ) function (from thejarray module) must be used, 
along with the type of the class for the resulting array. Any time you 
need to return an array to J ava, you must usearray( ), as seen in the 
methods ints( ) and doubles( ). 

The last methods show how to pass arguments in from J ava. Basic types 
happen automatically as long as you specify them in the@sig string, but 
you must use objects and you cannot pass in primitives (that is, 
primitives must be ensconced in wrapper objects, such as Integer). 

In argln3( ), you can see that a J ava List is transparently converted to 
something that behaves just like a Python array, but is not a true array 
because you cannot take a si ice from it. If you want a true Python array, 
then you must create and pass a PyArray as in argln4( ), wheretheslice 
is successful. Similarly, a J ava Map must come in as a PyDictionary in 
order to be treated as a Python dictionary. 



H ere is the Java program to exercise the Java classes produced by the 
above Python code.Thisalso introducesthe'=D' directivefor the 
makefile builder tool, which specifies a dependency in addition to those 
detected by the tool . H ere, you can't compi I e 

TestPythonToJavaClass.java until PythonToJavaClass.class is available: 

// : c09 : TestPythonTo JavaClass . java 

//+D python\ j ava\t est \PythonTo JavaClass .class 

import java . lang . reflect . * ; 

import java. util.*; 

import org . python . core . * ; 

import com . bruceeckel . test .* ; 

import com . bruceeckel . util .* ; 

import com . bruceeckel . python . * ; 

// The package with the Python-generated classes: 
import python . java . test . * ; 

public class 

TestPythonTo JavaClass extends UnitTest { 

PythonTo JavaClass p2 j = new PythonTo JavaClass () ; 
public void testl() { 
p2 j . simple ( ) ; 

System . out . print In (p2 j . ret urn St ring ( ) ) ; 
Arrays2 . print (p2 j . returnArray ( ) ) ; 
Arrays 2 .print (p2 j . ints ( ) ) ; 
Arrays2 . print (p2 j . doubles ( ) ) ; 
p2 j . arglnl ( "Testing arglnl ( ) " ) ; 
p2 j . argln2 (new Integer ( 4 7 ) ) ; 
ArrayList a = new ArrayList () ; 
for(int i = 0; i < 10; i++) 

a. add (new Integer (i)); 
p2 j . argln3 (a) ; 
p2 j . argln4 ( 

new PyArray ( Integer . class , a . toArray ( ) ) ) ; 
HashMap m = new HashMapO; 
for(int i = 0; i < 10; i++) 

m.put (" " + i, new Float (i)); 
p2 j . argln5 (PyUtil . toPyDictionary (m) ) ; 

} 

public void dumpClassInf o ( ) { 
Arrays 2 .print ( 

p2 j . getClass ( ) . getConstructors ( ) ) ; 
Method [ ] methods = 

p2 j . getClass ( ) . getMethods ( ) ; 



for(int i = 0; i < methods . length; i++) { 
String nm = methods [ i ]. toString () ; 
if (nm. indexOf ( "PythonToJavaClass" ) != -1) 
System . out . print In (nm) ; 

} 

} 

public static void main ( String [ ] args) { 
TestPythonTo JavaClass test = 

new TestPythonTo JavaClass () ; 
test . dumpClassInf o ( ) ; 
test .testl () ; 

} 

} 

For Python support, you'll usually only need to import the classes in 
org.python.core. Everything elsein the above example is fairly 
straightforward, as PythonToJavaClass appears, from thejava side, to be 
just another Java class. dumpClasslnfo( ) uses reflection to verify that the 
method signatures specified in PythonToJavaClass.py havecome 
through properly. 

Building thejava classes from the 
Python code 

Part of the tri ck of creati ng J ava cl asses from Python code i s the @5i g 
information in the method documentation strings. But there's a second 
problem which stems from the fact that Python has no "package" 
keyword - the Python equivalent of packages, modules, areimplicitly 
created based on thefilename. However, to bring the resulting class files 
into thejava program, jythonc must be given information about how to 
create thejava package for the Python code. This is done on the jythonc 
command line using the --package flag, followed by the package name 
you wish to produce (including the separation dots, just as you would 
give the package name using the package keyword in a J ava program). 
Thiswill put the resulting .class files in the appropriate subdirectory off 
of the current directory. Then you only need to import the package in 
your J ava program, as shown above (you'll need '.' in your CLASSPATH 
in order to run it from the code directory). 

H ere are the make dependency rules that I used to build the above 
example (the backslashes at the ends of the li nes are understood by make 



to be I i ne conti nuati ons). These rul es are encoded i nto the above J ava and 
Python files using the comment syntax that's understood by my makefile 
builder tool: 

TestPythonTo JavaClass . class : \ 

TestPythonTo JavaClass . java \ 
python \ java\ test \PythonTo JavaClass .class 
javac TestPythonTo JavaClass . java 

python \ java\ test \PythonTo JavaClass .class : \ 
PythonTo JavaClass . py 
jythonc — package python . java . test \ 
PythonTo JavaClass . py 

The first target, TestPythonToJavaC I assxl ass, depends on both 
TestPythonToJavaClass.java and the PythonTo) avaC I ass.cl ass, which is 
the Python code that's converted to a class file. This latter, in turn, 
depends on the Python source code. Note that it's important that the 
d i rectory w here the target I i ves be specif i ed , so that the makef i I e w i 1 1 
create thej ava program with the minimum necessary amount of 
rebuilding. 



Thischapter has arguably gone much deeper intojython than required to 
use the interpreter design pattern. Indeed, once you decidethatyou need 
to use i nterpreter and that you're not goi ng to get I ost i nventi ng your 
own language, thesolution of install ing J ython is quite simple, and you 
can at I east get started by f ol I ow i ng the G reen H ouseC ontrol I er exampl e. 

Of course, that example is often too simple and you may need something 
more sophisticated, often requiring more i nteresti ng data to be passed 
back and forth. When I encountered the limited documentation, I felt it 
necessary to come up with a more thorough examination of Jython. 

I n the process, note that there could be another equally powerful design 
pattern lurking in here, which could perhaps be called multiple languages. 
This is based on the experience of having each language solve a certain 
class of problems better than the other; by combining languages you can 
solve problems much faster than with either language by itself. CO RBA 




is another way to bridge across languages, and at the same time bridging 
between computers and operating systems. 

To me, Python and Java present a very potent combination for program 
development because of Java's architecture and tool set, and Python's 
extremely rapid development (generally considered to be 5- 10 times 
faster than C-H-orJava). Python is usually slower, however, but even if 
you end up re-coding parts of your program for speed, the initial fast 
development will allow you to more quickly flesh out the system and 
uncover and solve the critical sections. And often, the execution speed of 
Python is not a problem - in those cases it's an even bigger win. A 
number of commercial products already usejava and Jython, and 
because of the terrific productivity leveragel expect to see this happen 
more in the future. 



1. Modify G reenH ouseLanguage.py so that it checks the times for 
the events and runs those events at the appropri ate ti mes. 

2. Createa Swing application with aJTextField (where the user will 
enter commands) and a JTextA rea (where the command results 
will bedisplayed). Connect to a Python Interpreter object so that 
theoutputwill be sent to the JTextA rea (which should scroll). 
You'll need to locate the Python Interpreter command that 
redirects the output to a Java stream. 

3. Modify G reenH ouseLanguage.py to add a master controller class 
(instead of the static array inside Event) and provide a run( ) 
method for each of the subclasses. Each run( ) should create and 
use an object from thestandard Java library during its execution. 
M od i fy G reen H ouseC ontrol I er.j ava to use thi s new cl ass. 

4. M odify the resulti ng G reenH ouseLanguage.py from exercise two 
to producejava classes (add the@5ig documentation strings to 
produce the correct J ava signatures, and createa makefile to build 
thejava .class files). Writeajava program that uses these classes. 




10: Callbacks 



Decoupling code behavior 

Observer, and a category of call backs called "multipledispatching (not in 
Design Patterns)" including theVisitor from Design Patterns. 

Observer 

Li ke the other forms of cal I back, thi s contai ns a hook poi nt where you can 
change code. The difference is in the observer's completely dynamic 
nature. Itisoften used for the specific case of changes based on other 
object's change of state, but is also the basis of event management. 
Anytime you want to decouplethe source of the call from the called code 
in a completely dynamic way. 

The observer pattern solves a fairly common problem: What if a group of 
objects needs to update themselves when some object changes state? This 
can be seen in the "model -view" aspect of Smalltalk's MVC (model-view- 
controller), or the almost-equivalent "Document- View Architecture." 
Suppose that you havesomedata (the "document") and more than one 
view, say a plot and a textual view. When you change the data, thetwo 
views must know to update themselves, and that's what the observer 
facilitates. It'sacommon enough problem that its solution has been made 
a part of the standard java.util library. 

There are two types of objects used to implement the observer pattern in 
Java. The bservable class keeps track of everybody who wants to be 
informed when a change happens, whether the "state" has changed or 
not. When someonesays "OK, everybody should check and potentially 
update themsel ves," the bservabl e cl ass performs thi s task by cal I i ng 
the notif yO bservers( ) method for each one on the I i st. The 
notifyO bservers( ) method is part of the base class bservable. 

There are actually two "things that change" in the observer pattern: the 
quantity of observing objects and the way an update occurs. That is, the 



observer pattern allows you to modify both of these without affecting the 
surrounding code. 



bserver is an "i nterface" class that only has one member function, 
update( ). This function is called by the object that's being observed, 
when that object decides its time to update all its observers. The 
arguments are optional; you could havean update( ) with no arguments 
and thatwould still fit the observer pattern; however this is more 
general— it al lows the observed object to pass the object that caused the 
update (si nee an Observer may be registered with more than one 
observed object) and any extra information if that's helpful, rather than 
forcing the Observer object to hunt around to see who is updating and to 
fetch any other information it needs. 

The "observed object" that decides when and how to do the updating 
will be called the Observable. 

Observable has a flag to indicate whether it's been changed. In a simpler 
design, there would be no flag; if something happened, everyonewould 
be notified. The flag allowsyou towait, and only notify the Observers 
when you decide the time is right. Notice, however, that the control of 
the flag's state is protected, so that only an inheritor can decide what 
constitutes a change, and not the end user of the resulting derived 
Observer class. 

Most of the work isdonein notifyObservers( ). If the changed flag has 
not been set, this does nothing. Otherwise, it first clears the changed flag 
so repeated calls to notifyObservers( ) won't waste time. This is done 
before notifying the observers in case the calls to update( ) do anything 
that causes a change back to this bservable object. Then it moves 
through the set and calls back to the update( ) member function of each 
bserver. 

At fi rst it may appear that you can use an ordi nary bservable object to 
manage the updates. But this doesn't work; to get an effect, you must 
inherit from Observable and somewhere in your derived-class code call 
setChanged( ). This is the member function that sets the "changed" flag, 
which means that when you call notifyObservers( ) all of the observers 



will, in fact, get notified. Where you call setChanged( ) depends on the 
logic of your program. 

Observing flowers 

H ere is an example of the observer pattern: 

//: clO : ObservedFlower . java 

// Demonstration of "observer" pattern. 

import java. util . *; 

import com . bruceeckel . test .* ; 

class Flower { 

private boolean isOpen; 
private OpenNotif ier oNotify = 

new OpenNotif ier () ; 
private CloseNotif ier cNotify = 

new CloseNotif ier () ; 
public Flower () { isOpen = false; } 
public void open ( ) { // Opens its petals 

isOpen = true; 

oNotif y . not ifyOb servers ( ) ; 

cNot i f y . open ( ) ; 

} 

public void close () { // Closes its petals 
isOpen = false; 
cNotif y . notifyObservers ( ) ; 
oNotif y .close () ; 

} 

public Observable opening () { return oNotify; } 
public Observable closing () { return cNotify; } 
private class OpenNotifier extends Observable { 
private boolean alreadyOpen = false; 
public void notifyObservers ( ) { 
if (isOpen && ! alreadyOpen) { 
setChanged ( ) ; 
super . notifyObservers ( ) ; 
alreadyOpen = true; 

} 

} 

public void close () { alreadyOpen = false; } 

} 

private class CloseNotif ier extends Observable{ 
private boolean alreadyClosed = false; 



public void notifyObservers ( ) { 
if ( ! isOpen && ! alreadyClosed) { 
setChanged ( ) ; 
super . notifyObservers ( ) ; 
alreadyClosed = true; 

} 

} 

public void open ( ) { alreadyClosed = false; } 




class Bee { 

private String name; 

private OpenObserver openObsrv = 

new OpenObserver () ; 
private CloseObserver closeObsrv = 

new CloseObserver () ; 
public Bee (String nm) { name = nm; } 
// An inner class for observing openings: 
private class OpenObserver implements Observer! 
public void update (Observable ob, Object a) { 
System . out . println ( "Bee " + name 
+ "'s breakfast time!"); 

} 

} 

// Another inner class for closings: 
private class CloseObserver implements Observer! 
public void update (Observable ob, Object a) { 
System. out .println ( "Bee " + name 
+ " ' s bed time ! " ) ; 

} 

} 

public Observer OpenObserver ( ) { 
return openObsrv; 

} 

public Observer CloseObserver ( ) { 
return closeObsrv; 

} 



class Hummingbird { 
private String name; 
private OpenObserver openObsrv = 
new OpenObserver () ; 



private CloseObserver closeObsrv = 

new CloseObserver () ; 
public Hummingbird (String nm) { name = nm; } 
private class OpenObserver implements Observer! 
public void update (Observable ob, Object a) { 
System. out .println ( "Hummingbird " + name 
+ "'s breakfast time!"); 

} 

} 

private class CloseObserver implements Observer! 
public void update (Observable ob, Object a) { 
System. out .println ( "Hummingbird " + name 
+ " ' s bed time ! ") ; 

} 

} 

public Observer openObserver ( ) { 
return openObsrv; 

} 

public Observer CloseObserver ( ) { 
return closeObsrv; 

} 



public class ObservedFlower extends UnitTest { 
Flower f = new Flower () ; 
Bee 

ba = new Bee ( "A" ) , 

bb = new Bee ( "B" ) ; 
Hummingbird 

ha = new Hummingbird ( "A" ) , 

hb = new Hummingbird ( "B" ) ; 
public void test() { 

f . opening ( ) . addObserver (ha . openObserver ( ) ) ; 

f . opening ( ) . addObserver (hb . openObserver ( ) ) ; 

f . opening ( ) . addObserver (ba . openObserver ( ) ) ; 

f . opening ( ) . addObserver (bb . openObserver ( ) ) ; 

f.closingO . addObserver (ha . CloseObserver ( ) ) ; 

f.closingO . addObserver (hb . CloseObserver ( ) ) ; 

f . closing ( ) . addObserver (ba . CloseObserver ( ) ) ; 

f.closingO . addObserver (bb . CloseObserver ( ) ) ; 

// Hummingbird B decides to sleep in: 

f. opening () . deleteObserver ( 
hb . openObserver ( ) ) ; 

// A change that interests observers: 



f . open ( ) ; 

f . open ( ) ; // It's already open, no change. 
// Bee A doesn't want to go to bed: 
f. closing () . deleteObserver ( 

ba . closeObserver ( ) ) ; 
f . c 1 o s e ( ) ; 

f. close (); // It's already closed; no change 
f . opening ( ) . deleteObservers ( ) ; 
f . open ( ) ; 
f . c 1 o s e ( ) ; 

} 

public static void main (String args [ ] ) { 
new ObservedFlower ( ) . test ( ) ; 

} 

} ///:- 

The events of interest are that a Flower can open or close. Because of the 
use of the inner class idiom, both these events can be separately 
observabl e phenomena. Open Notifier and CloseNotifier both inherit 
bservable, so they have access to sett hanged ( ) and can be handed to 
anything that needs an Observable. 

The inner class idiom also comes in handy to define more than one kind 
of Observer, in Bee and Hummingbird, since both those classes may 
want to independently observe Flower openings and closings. Notice 
how the inner class idiom provides something that has most of the 
benefits of i nheritance (the abi I ity to access the private data i n the outer 
class, for example) without the same restrictions. 

In main(), you can see one of the prime benefits of the observer pattern: 
the abi I ity to change behavi or at run ti me by dynami cal I y regi steri ng and 
un-registering Observers with Observabl es. 

If you study the code above you 'I I see that Open Notifier and 
C loseN otif i er use the basi c bservabl e i nterface. This means that you 
could inherit other completely different bserver classes; the only 
connection theObservers havewith Flowers istheObserver interface. 



A visual example of 
observers 

The f ol I owi ng exampl e is si mi I ar to the C ol orBoxes example from 
Chapter 14 in Thinking in Java, 2 nd Edition. Boxes are placed in agrid on 
the screen and each one is initialized to a random color. In addition, each 
box i mplements the bserver i nterface and is registered with an 
bservabl e object. When you cl i ck on a box, al I of the other boxes are 
notifi ed that a change has been made because the bservable object 
automati cal I y cal I s each bserver object's update( ) method . I nsi de thi s 
method, the box checks to see if it's adjacent to the one that was clicked, 
and if so it changes its color to match the clicked box. 

//: cl : BoxObserver . java 

// Demonstration of Observer pattern using 

// Java's built-in observer classes. 

import javax . swing . * ; 

import java.awt.*; 

import java. awt . event . *; 

import java . util . * ; 

import com . bruceeckel . swing . * ; 

// You must inherit a new type of Observable: 
class BoxObservable extends Observable { 
public void notifyObservers (Object b) { 

// Otherwise it won't propagate changes: 

setChanged ( ) ; 

super . notifyObservers (b) ; 




public class BoxObserver extends JFrame { 
Observable notifier = new BoxObservable () ; 
public BoxObserver (int grid) { 

setTitle ( "Demonstrates Observer pattern"); 
Container cp = getContentPane ( ) ; 
cp . setLayout (new GridLayout (grid, grid)); 
for (int x = 0; x < grid; x++) 
for (int y = 0; y < grid; y++) 

cp. add (new OCBox (x, y, notifier)); 

} 



public static void main ( String [ ] args) { 
int grid = 8; 
if (args . length > 0) 

grid = Integer . parselnt (args [ ]) ; 
JFrame f = new BoxObserver (grid) ; 
f . setSize (500, 400); 
f . setVisible (true) ; 
// JDK 1.3: 

f . setDefaultCloseOperation (EXIT_ON_CLOSE) ; 
// Add a WindowAdapter if you have JDK 1.2 




class OCBox extends JPanel implements Observer { 

Observable notifier; 

int x, y; // Locations in grid 

Color cColor = newColor () ; 

static final Color [] colors = { 

Color. black, Color. blue, Color. cyan, 
Color . darkGray, Color. gray, Color. green, 
Color . lightGray, Color . magenta, 
Color . orange, Color. pink, Color. red, 
Color. white, Color. yellow 

} ; 

static final Color newColor () { 
return colors [ 

(int) (Math . random ( ) * colors . length) 

] ; 

} 

OCBox (int x, int y, Observable notifier) { 
this.x = x; 
this.y = y; 

notifier . addObserver (this) ; 
this . notifier = notifier; 
addMouseListener (new ML ( ) ) ; 

} 

public void paintComponent (Graphics g) { 
super . paintComponent (g) ; 
g. setColor (cColor) ; 
Dimension s = getSize(); 
g. f illRect (0, 0, s. width, s. height); 

} 

class ML extends MouseAdapter { 

public void mousePressed (MouseEvent e) { 



notif ier . notif yObservers (OCBox.this) ; 

} 

} 

public void update (Observable o, Object arg) { 
OCBox clicked = (OCBox) arg; 
if (nextTo (clicked) ) { 

cColor = clicked . cColor; 
repaint ( ) ; 

} 

} 

private final boolean nextTo (OCBox b) { 
return Math.abs(x - b.x) <= 1 && 
Math.abs(y - b.y) <= 1; 

} 

} III:- 

When you first look at the online documentation for Observable, it's a bit 
confusing because it appears that you can use an ordinary Observable 
object to manage the updates. But this doesn't work; try it— inside 
BoxObserver, create an Observable object instead of a BoxObservable 
object and see what happens: nothing. To get an effect, you must inherit 
from Observable and somewhere in your derived -class code call 
setChanged( ). This is the method that sets the "changed" flag, which 
means that when you call notifyObservers( ) all of the observers will, in 
fact, get notified. In the example above sett hanged ( ) issimply called 
within notif yObservers( ), but you could use any criterion you want to 
decide when to call setC hanged ( ). 

BoxObserver contains a single Observable object called notif ier, and 
every time an OCBox object is created, it is tied to notif ier. In OCBox, 
whenever you click the mouse the notifyObservers( ) method iscalled, 
passing the clicked objectin as an argument so that all the boxes 
receiving the message (in their update( ) method) know who was clicked 
and can decide whether to change themselves or not. Using a 
combination of code in notif yObservers( ) and update( ) you can work 
out some f ai rl y compl ex schemes. 

It might appear that theway the observers are notified must be frozen at 
compiletimein thenotifyObservers( ) method. However, if you look 
more closely at the code above you'll see that the only placein 
BoxObserver or OCBox where you're aware that you'reworking with a 



BoxO bservable is at the poi nt of creation of the bservable object— from 
then on everythi ng uses the basic bservable i nterface. This means that 
you could inherit other Observable classes and swap them at run time if 
you want to change notification behavior then. 



1. Create a minimal Observer-Observable design in two classes. Just 
create the bare minimum in the two classes, then demonstrate 
your design by creating oneObservable and many bservers, 
and cause the Observable to update the Observers. 

2. Modify BoxO bserver Java to turn it into a simple game. If any of 
the squares surrounding the one you clicked is part of a 
contiguous patch of the same col or, then all the squares in that 
patch are ch an ged to th e col or y ou cl i eked on . Y ou can conf i g u re 
the game for competition between players or to keep track of the 
nu mber of cl i cks that a si ngl e pi ayer uses to tu rn the f i el d i nto a 
si ngl e col or. You may al so want to restri ct a pi ayer's col or to the 
first onethat was chosen. 




11: Multiple 
dispatching 

When dealing with multipletypes which are interacting, a program can 
get particularly messy. For example, consider a system that parses and 
executes mathemati cal expressi ons. You want to be abl e to say N umber + 
Number, Number* Number, etc., where Number is the base class for a 
family of numerical objects. But when you say a + b, and you don't know 
the exact type of e ther a or b, so how can you get them to i nteract 
properly? 

The answer starts with something you probably don't think about: Java 
performs only si ngle dispatching. That is, if you are performing an 
operation on more than one object whose typeis unknown, Java can 
invoke the dynamic binding mechanism on only one of those types. This 
doesn't solve the problem, so you end up detecting some types manually 
and effectively producing your own dynamic binding behavior. 

Thesolution is called multiple dispatching. Remember that polymorphism 
can occur only via member function calls, so if you want double 
d i spatch i n g to occu r , th ere mu st be tw o member f u n cti on cal I s: th e f i rst to 
determine the first unknown type, and thesecond to deter mine the 
second unknown type. With multiple dispatching, you must have a 
polymorphic method call to determine each of the types. Generally, 
you'll set up a configuration such that a single member function call 
produces more than one dynamic member function call and thus 
determines more than one type in the process. To get this effect, you need 
to work with more than one polymorphic method call: you'll need one 
call for each dispatch. The methods in thefollowing example are cal led 
compete( ) and eval( ), and are both members of the same type. (In this 
case there will be only two dispatches, which is referred to as double 
dispatching). If you areworking with two different type hierarchies that 
are interacting, then you'll haveto have a polymorphic method call in 
each hierarchy. 



Here's an exampleof multiple dispatching: 



//: cl 1 : PaperScissorsRock . java 

// Demonstration of multiple dispatching 

import java . util . * ; 

import com . bruceeckel . test .* ; 

// An enumeration type: 
class Outcome { 

private int value; 

private String name; 

private Outcome (int val, String nm) { 
value = val; 
name = nm; 

} 

public final static Outcome 
WIN = new Outcome (0, "win"), 
LOSE = new Outcome (1, "lose"), 
DRAW = new Outcome (2, "draw"); 
public String toStringO { return name 
public boolean equals (Object o) { 
return (o instanceof Outcome) 

&& (value == ( (Outcome) o) .value) ; 

} 

} 



interface Item { 

Outcome compete (Item it) 
Outcome eval (Paper p) ; 
Outcome eval (Scissors s) 
Outcome eval (Rock r) ; 



class Paper implements Item { 

public Outcome compete (Item it) { 
return it . eval (this) ; 

} 

public Outcome eval (Paper p) { 
return Outcome . DRAW; 

} 

public Outcome eval (Scissors s) { 
return Outcome. WIN; 

} 

public Outcome eval (Rock r) { 
return Outcome . LOSE; 



} 

public String toStringO { return "Paper"; } 

} 



class Scissors implements Item { 
public Outcome compete (Item it) { 
return it . eval (this) ; 

} 

public Outcome eval (Paper p) { 
return Outcome . LOSE; 

} 

public Outcome eval (Scissors s) { 
return Outcome . DRAW; 

} 

public Outcome eval (Rock r) { 
return Outcome. WIN; 

} 

public String toStringO { return "Scissors"; 



class Rock implements Item { 

public Outcome compete (Item it) { 
return it . eval (this) ; 

} 

public Outcome eval (Paper p) { 
return Outcome. WIN; 

} 

public Outcome eval (Scissors s) { 
return Outcome . LOSE; 

} 

public Outcome eval (Rock r) { 
return Outcome . DRAW; 

} 

public String toStringO { return "Rock"; } 



class ItemGenerator { 

public static Item newltemf) { 

switch ( (int) (Math. random () * 3)) { 
default : 
case : 

return new Scissors () ; 
case 1 : 

return new Paper (); 



case 2 : 

return new Rock ( ) ; 

} 

} 

} 

class Compete { 

public static Outcome match (Item a, Item b) { 
System. out .print (a + " < — > " + b + " : "); 
return a . compete (b) ; 

} 

} 

public class PaperScissorsRock extends UnitTest { 
List items = new ArrayList ( ) ; 
public PaperScissorsRock ( ) { 
for(int i = 0; i < 40; i++) 

items . add ( ItemGenerator . newltem ( ) ) ; 

} 

public void test() { 

for(int i = 0; i < items . size () /2 ; i++) 
System . out . print In ( 
Compete . match ( 

(Item) items . get ( i ) , 
(Item) items . get (i*2) ) ) ; 

} 

public static void main (String args [ ] ) { 
new PaperScissorsRock (). test () ; 

} 

} ///:- 

Visitor, a type of multiple 
dispatching 

The assumption is that you have a primary class hierarchy that is fixed; 
perhaps it's from another vendor and you can't make changes to that 
hierarchy. However, you'd I ike to add new polymorphic methods to that 
hierarchy, which means that normally you'd have to add something to 



the base class interface. So the di lemma is that you need to add methods 
to the base class, but you can't touch the base class. H ow do you get 
around this? 

Thedesign pattern that solves this kind of problem is called a "visitor" 
(thefinal one in the Design Patterns book), and it builds on thedouble 
dispatching scheme shown in the last section. 

The vi sitor pattern al I ows you to extend the i nterface of the pri mary type 
by creati ng a separate cl ass hi erarchy of type V i sitor to vi rtual i ze the 
operations performed upon the primary type. The objects of the pri mary 
type simply "accept" the visitor, then call the visitor's dynamically- 
bound member function. 

//: cl 1 : BeeAndFlowers . java 

// Demonstration of "visitor" pattern. 

import java . util . * ; 

import com . bruceeckel . test .* ; 

interface Visitor { 

void visit (Gladiolus g) ; 
void visit (Renuculus r) ; 
void visit (Chrysanthemum c) ; 

} 

// The Flower hierarchy cannot be changed: 
interface Flower { 

void accept (Visitor v) ; 

} 

class Gladiolus implements Flower { 

public void accept (Visitor v) { v. visit (this) ; } 

} 

class Renuculus implements Flower { 

public void accept (Visitor v) { v. visit (this) ; } 

} 

class Chrysanthemum implements Flower { 

public void accept (Visitor v) { v. visit (this) ; } 

} 

// Add the ability to produce a string: 
class StringVal implements Visitor { 



String s; 

public String toStringO { return s; } 
public void visit (Gladiolus g) { 
s = "Gladiolus"; 

} 

public void visit (Renuculus r) { 
s = "Renuculus"; 

} 

public void visit (Chrysanthemum c) { 
s = "Chrysanthemum"; 

} 



// Add the ability to do "Bee" activities: 
class Bee implements Visitor { 
public void visit (Gladiolus g) { 

System. out .println ( "Bee and Gladiolus"); 

} 

public void visit (Renuculus r) { 

System. out .println ( "Bee and Renuculus"); 

} 

public void visit (Chrysanthemum c) { 

System. out .println ( "Bee and Chrysanthemum 

} 



class FlowerGenerator { 

public static Flower newFlower () { 
switch ( (int) (Math . random ( ) * 3) ) { 
default : 

case 0: return new Gladiolus (); 
case 1: return new Renuculus () ; 
case 2: return new Chrysanthemum () ; 




public class BeeAndFlowers extends UnitTest { 
List flowers = new ArrayList ( ) ; 
public BeeAndFlowers ( ) { 

for (int i = 0; i < 10; i + +) 

flowers . add (FlowerGenerator . newFlower ( ) 

} 

public void test() { 



// It's almost as if I had a function to 
// produce a Flower string representation: 
StringVal sval = new StringVal () ; 
Iterator it = flowers . iterator () ; 
while (it .hasNext () ) { 

( (Flower) it . next ( ) ) . accept ( sval ) ; 

System. out .print In (sval) ; 

} 

// Perform "Bee" operation on all Flowers: 

Bee bee = new Bee(); 

it = f lowers . iterator () ; 

while ( it . hasNext ( ) ) 

( (Flower) it . next ( ) ) . accept (bee) ; 

} 

public static void main (String args [ ] ) { 
new BeeAndFlowers ( ) . test ( ) ; 

} 

} ///:~ 



Exercises 

1. Create a business- mod ding environment with three types of 
Inhabitant: Dwarf (for engineers), Elf (for marketers) and Troll 
(for managers). Now create a class called Project that creates the 
different inhabitants and causes them to interact( ) with each 
other using multipledispatching. 

2. M odify the above exampl e to make the i nteracti ons more detai I ed . 
Each Inhabitant can randomly produce a Weapon using 
getWeapon( ): a Dwarf uses J argon or Play, an Elf uses 
InventFeatureor Sell I magi nary Product, and a Troll uses Edict 
and Schedule. You must decide which weapons "win" and "lose" 
in each interaction (as in Papers cissorsRock Java). Add a battle( ) 
member function to Project that takes two Inhabitants and 
matches them agai nst each other. N ow create a meeting! ) 
member function for Project that creates groups of D warf , Elf and 
M anager and battles the groups against each other until only 
members of one group are left standi ng. These are the "wi nners." 



3. Modify the above example to replacethe double dispatching with 
atablelookup instead, using a structure similar to 
TransitionTable.java. Notice how much easier it is to reconfigure 
the system. When is it more appropriate to use this approach vs. 
hard-coding the dynamic dispatches? Can you create a system 
that has the simplicity of use of the dynamic dispatch but uses a 
table lookup? 



12: Pattern 
refactoring 



The remainder of the book will look at the process of solving a problem 
by applying design patterns in an evolutionary fashion. That is, a first cut 
design will be used for theinitial solution, and then thissolution will be 
examined and various design patternswill be applied to the problem 
(some of which will work, and some of which won't). The key question 
thatwill always be asked in seeking improved solutions is "what will 
change?" 

This process is similar to what M artin Fowler talks about in his book 
Refactoring: Improving theDesign of Existing Code^although he tends to 
talk about pieces of code more than pattern-level designs). You start with 
a solution, and then when you discover that it doesn't continue to meet 
your needs, you fix it. Of course, this is a natural tendency but in 
computer programming it's been extremely difficultto accomplish with 
procedural programs, and the acceptance of the idea that we can refactor 
code and designs adds to the body of proof that object-oriented 
programming is "a good thing." 



The nature of this problem is that the trash isthrown unclassified into a 
single bin, so the specific type information is lost. But later, the specific 
type i nformation must be recovered to properly sort thetrash. I n the 
initial solution, RTTI (described in Chapter 12 of Thinking in Java, 2 nd 
edition) isused. 




iAddison-Wesley, 1999. 



This is not a trivial design because it has an added constraint. That's what 
makes it i nteresti ng— it's more I i ke the messy probl ems you're I i kel y to 
encounter i n your work. The extra constrai nt i s that the trash arrives at 
the trash recycling plant all mixed together. The program must model the 
sorting of that trash. This is where RTTI comesin: you havea bunch of 
anonymous pieces of trash, and the program figures out exactly what 
type they are. 

//: cl2 : recyclea : RecycleA. java 

// Recycling with RTTI. 

import java . util . * ; 

import java.io.*; 

import com . bruceeckel . test .* ; 

abstract class Trash { 
private double weight; 
Trash (double wt) { weight = wt; } 
abstract double getValue (); 
double getWeight() { return weight; } 
// Sums the value of Trash in a bin: 
static void sumValue (Collection bin) { 
Iterator e = bin . iterator () ; 
double val = O.Of; 
while (e . hasNext () ) { 
// One kind of RTTI: 
// A dynamically-checked cast 
Trash t = (Trash) e . next () ; 
// Polymorphism in action: 
val += t . getWeight ( ) * t . getValue () ; 
System. out .print In ( 
"weight of " + 
// Using RTTI to get type 
// information about the class: 
t . getClass ( ) . getName ( ) + 
" = " + t . getWeight ( ) ) ; 

} 

System. out .println ( "Total value = " + val); 




class Aluminum extends Trash { 
static double val = 1.67f; 
Aluminum (double wt) { super(wt); } 
double getValue () { return val; } 



static 
val 

} 



void setValue (double 
= newval; 



newval ) 



{ 



class Paper extends Trash { 
static double val = O.lOf; 
Paper (double wt) { super (wt); } 
double getValue() { return val; } 
static void setValue (double newval) { 
val = newval; 

} 



class Glass extends Trash { 
static double val = 0.23f; 
Glass (double wt) { super (wt); } 
double getValue() { return val; } 
static void setValue (double newval) { 
val = newval; 

} 



public class RecycleA extends UnitTest { 
Collection 

bin = new ArrayList ( ) , 
glassBin = new ArrayList (), 
paperBin = new ArrayList (), 
alBin = new ArrayList (); 
public RecycleA () { 

// Fill up the Trash bin: 
for(int i = 0; i < 30; i++) 

switch ( (int) (Math. random ( ) * 3)) { 
case : 

bin . add (new 

Aluminum (Math. random ( ) * 100)); 
break; 
case 1 : 

bin . add (new 

Paper (Math. random () * 100)); 
break; 
case 2 : 

bin . add (new 

Glass (Math. random () * 100)); 




public void test() { 

Iterator sorter = bin . iterator () ; 
// Sort the Trash: 
while ( sorter . hasNext () ) { 
Object t = sorter . next () ; 
// RTTI to show class membership: 
if (t instanceof Aluminum) 

alBin . add (t ) ; 
if (t instanceof Paper) 

paperBin . add (t ) ; 
if (t instanceof Glass) 
glassBin . add (t ) ; 

} 

Trash. sumValue (alBin) ; 
Trash. sumValue (paperBin) ; 
Trash. sumValue (glassBin) ; 
Trash. sumValue (bin) ; 

} 

public static void main (String args [ ] ) { 
new RecycleA ( ) . test ( ) ; 

} 

} ///:~ 



I n the sou rce cod e I i sti ngs avai I abl e for th i s book, th i s f i I e w i 1 1 be pi aced 
i n the su bd i rectory recycl ea that branches off from the su bd i rectory cl2 
(for Chapter 12). The unpacking tool takes care of placing it into the 
correct subdirectory. The reason for doing this is that this chapter 
rewrites this particular example a number of times and by putting each 
version in its own directory (using the default package in each directory 
so that i nvoki ng the program i s easy), the cl ass names will not cl ash. 

Several Array List objects are created to hold Trash references. Of course, 
Array Lists actually hold Objects so they'll hold anything at all. The 
reason they hold Trash (or something derived from Trash) is only 
because you've been careful to not put in anything exceptTrash. If you 
do put something "wrong" into theArrayList, you won't get any 
compile- time warnings or errors— you'll find out only via an exception at 
run time. 



When the Trash references are added, they lose their specific identities 
and become simply Object references (they are upcast). However, 
because of polymorphism the proper behavior still occurswhen the 
dynamically-bound methods are called through the Iterator sorter, once 
the resulting bject has been cast back to Trash. sumValue( ) also uses 
an Iterator to perform operations on every object in theArrayList. 

It looks silly to upcast the types of Trash into a container holding base 
type references, and then turn around and downcast. Why not just put 
the trash i nto the appropri ate receptad e i n the f i rst pi ace? (I ndeed, this is 
the w hoi e enigma of recycl i ng). I n this program it woul d be easy to 
repair, but sometimes a system's structure and flexibility can benefit 
greatly from downcasting. 

The program satisfies the design requirements: it works. This might be 
fine as long as it's a one-shot solution. H owever, a useful program tends 
to evolve over time, so you must ask, "What if the situation changes?" 
For example, cardboard is now a valuable recycl able commodity, so how 
will that be i nteg rated into the system (especially if the program is large 
and complicated). Si nee the above type-check coding in the switch 
statement could be scattered throughout the program, you must go find 
all thatcodeevery timea new typeisadded, and if you missonethe 
compiler won't give you any help by pointing out an error. 

The key to the misuse of RTTI here is that every typeis tested. If you're 
looking for only a subset of types because that subset needs special 
treatment, that's probably fine. But if you're hunting for every type inside 
a switch statement, then you're probably missing an important point, and 
d ef i n i tel y maki n g y ou r cod e I ess mai ntai n abl e. I n the n ext secti on w e' 1 1 
look at how this program evolved over several stages to become much 
more flexible. Thisshould prove a valuable example in program design. 

Improving the design 

The solutions in Design Patterns are organized around the question 
"What will change as this program evolves?" This is usually the most 
important question that you can ask about any design. If you can build 
your system around the answer, the results will be two- pronged: not only 
will your system allow easy (and inexpensive) maintenance, but you 
might also produce components that are reusable, so that other systems 



can be built more cheaply. This is the promise of object-oriented 
programming, but it doesn't happen automatically; it requires thought 
and insight on your part. In this section we'll see how this process can 
happen during the refinement of a system. 

The answer to the question "Whatwill change?" for the recycling system 
is a common one: more types will be added to the system. The goal of the 
design, then, is to make this addition of types as painless as possible. In 
the recycling program, we'd I ike to encapsulate all places where specific 
type information is mentioned, so (if for no other reason) any changes 
can belocalized to those encapsulations. Itturns out that this process also 
cl eans up the rest of the code considerably. 

"Make more objects" 

This brings up a general object-oriented design principle that I first heard 
spoken by Grady Booch: "If the design is too complicated, make more 
obj ects. " Th i s i s si mu I taneou si y cou nteri ntu i ti ve and I u d i crousl y si mpl e, 
and yet it's the most useful guiddinel'vefound. (You might observe that 
"making more objects" isoften equivalent to "add another level of 
indirection.") In general, if you find a pi ace with messy code, consider 
what sort of class would clean that up. Often the side effect of clean i ng 
up the code will be a system that has better structure and i s more f I exi bl e. 

Consider first the pi ace where Trash objects are created, which isa 
switch statement inside main( ): 

for(int i = 0; i < 30; i++) 

switch ( (int) (Math. random ( ) * 3)) { 
case : 

bin . add (new 

Aluminum (Math. random ( ) * 10 0)); 
break; 
case 1 : 

bin . add (new 

Paper (Math . random ( ) * 100)); 
break; 
case 2 : 

bin . add (new 

Glass (Math. random () * 100)); 

} 



This is definitely messy, and also a pi ace where you must change code 
whenever a new type is added. If new types are commonly added, a 
better solution is a single method that takes all of the necessary 
information and producesa reference to an object of the correct type, 
already upcast to a trash object. In Design Patterns this is broadly referred 
toasacreational pattern (of which there are several). The specific pattern 
that w i 1 1 be appl i ed here i s a vari ant of the F actory M ethod . H ere, the 
factory method is a static member of Trash, but more commonly it is a 
method that is overridden in thederived class. 

Theideaof the factory method isthatyou pass it the essential 
information it needs to know to create your object, then stand back and 
wait for the reference (al ready upcast to the base type) to pop out as the 
return value. From then on, you treat the object polymorphically. Thus, 
you never even need to know the exact type of object that's created. I n 
fact, thefactory method hides itfrom you to prevent accidental misuse. If 
you want to use the object without polymorphism, you must explicitly 
useRTTI and casting. 

But there's a I ittle probl em, especi al I y w hen you use the more 
complicated approach (not shown here) of making thefactory method in 
the base class and overriding it in thederived classes. What if the 
information required in thederived class requires more or different 
arguments? "Creating more objects" solves this problem. To implement 
thefactory method, the Trash class gets a new method called factory. To 
hi de the creati onal data, there's a new cl ass cal I ed M essenger that carri es 
al I of the necessary i nf ormati on for the factory method to create the 
appropriate Trash object (we'vestarted referring to M essenger as a design 
pattern, but it's simple enough that you may not choose to elevate it to 
that status). H ere's a simple implementation of M essenger: 

class Messenger { 
int type; 

// Must change this to add another type: 
static final int MAX_NUM = 4; 
double data; 

Messenger ( int typeNum, double val) { 
type = typeNum % MAX_NUM; 
data = val; 

} 

} 



A Messenger object's onlyjob is to hold information for the factory( ) 
method. Now, if there's a situation in which factory( ) needs more or 
different information to createa new type of Trash object, thefactory( ) 
i nterface doesn't need to be changed . The M essenger cl ass can be 
changed by adding new data and new constructors, or in the more 
typical object-oriented fashion of subclassing. 

Thefactory( ) method for this simple example looks I ike this: 

static Trash factory (Messenger i) { 
switch (i . type) { 

default: // To quiet the compiler 
case : 

return new Aluminum ( i . data) ; 
case 1 : 

return new Paper (i . data) ; 
case 2 : 

return new Glass (i . data) ; 
// Two lines here: 
case 3 : 

return new Cardboard (i . data) ; : 




Here, the determination of the exact type of object is simple, but you can 
imagine a more complicated system in which factory! ) uses an elaborate 
algorithm. The point is that it's now hidden away in one pi ace, and you 
know to come to this place when you add new types. 

The creation of new objects is now much simpler in main( ): 

for(int i = 0; i < 30; i++) 
bin . add ( 

Trash. factory ( 
new Messenger ( 

(int ) (Math . random ( ) * Messenger .MAX_NUM) , 
Math. random () * 100))); 

A M essenger object is created to passthedata into factory( ), which in 
turn produces some kind of Trash object on the heap and returns the 
reference that's added totheArrayListbin. Of course, if you change the 
quantity and type of argument, this statement will still need to be 



mod if i ed , but that can be el i mi nated i f the creati on of the M essenger 
object is automated. For example, an Array List of arguments can be 
passed i nto the constructor of a M essenger object (or directly i nto a 
f actory( ) cal I , for that matter). This requi res that the arguments be parsed 
and checked at run time, but it does provide the greatest flexibility. 

You can see from this code what "vector of change" problem the factory 
is responsible for solving: if you add new types to the system (the 
change), the only code that must be modified is within thefactory, so the 
factory isolates the effect of that change. 

A pattern for prototyping 
creation 

A problem with the design above isthat it still requires a central location 
where al I the types of the objects must be known: i nsi de the f actory( ) 
method. If new types are regularly being added to the system, the 
f actory( ) method must be changed for each new type. When you 
discover something likethis, it is useful to try to go one step further and 
moveall of the information about thetype— including its creati on— into 
the cl ass representi ng that type. This way, the onl y thi ng you need to do 
to add a new type to the system is to inherit a single class. 

To move the information concerning type creati on into each specific type 
of Trash, the "prototype" pattern (from the Design Patterns book) will be 
used. The general idea isthat you have a master sequence of objects, one 
of each type you're i nterested i n maki ng. The objects i n thi s sequence are 
used only for making new objects, using an operation that's not unlikethe 
cloneOschemebuiltintoJava'srootclassObject. In this case, we'll name 
the cloning method tClone( ). When you're ready to makea new object, 
presumably you have some sort of information that establishes the type 
of object you want to create, then you move through the master sequence 
comparing your information with whatever appropriate information is in 
the prototype objects in the master sequence. When you find one that 
matches your needs, you clone it. 

In this scheme there is no hard -coded information for creation. Each 
object knows how to expose appropriate information and how to clone 



itself. Thus, thefactory( ) method doesn't need to be changed when a 
new type is added to the system. 

One approach to the problem of prototyping is to add a number of 
methods to support the creation of new objects. However, in Java 1.1 
there's already support for creating new objects if you have a reference to 
the CI ass object. With Java 1.1 reflection (introduced in Chapter 12 of 
Thinking in Java, 2 nd edition) you can call a constructor even if you have 
only a reference to the Class object. This is the perfect solution for the 
prototyping problem. 

The I i st of prototypes will be represented i ndi recti y by a I ist of references 
to all theClass objects you want to create. In addition, if the prototyping 
fails, thefactory( ) method will assume that it's because a particular Class 
object wasn't in thelist, and it will attempt to load it. By loading the 
prototypes dynamically likethis, theTrash class doesn't need to know 
what types it is working with, so it doesn't need any modifications when 
you add new types. This allows it to be easily reused throughout the rest 
of the chapter. 

//: cl2 : trash : Trash . java 

// Base class for Trash recycling examples. 

package cl2. trash; 

import java . util . * ; 

import java . lang . reflect . * ; 

public abstract class Trash { 
private double weight; 

public Trash (double wt) { weight = wt; } 
public Trash ( ) { } 

public abstract double getValue(); 
public double getWeight() { return weight; } 
// Sums the value of Trash given an 
// Iterator to any container of Trash: 
public static void sumValue ( Iterator it) { 
double val = O.Of; 
while (it .hasNext () ) { 
// One kind of RTTI: 
// A dynamically-checked cast 
Trash t = (Trash) it . next () ; 
val += t . getWeight ( ) * t . getValue ( ) ; 
System. out .print In ( 
"weight of " + 



// Using RTTI to get type 

// information about the class: 

t . getClass ( ) . getName ( ) + 

" = " + t . getWeight ( ) ) ; 

} 

System. out .println ( "Total value = " + val); 

} 

// Remainder of class provides 
// support for prototyping: 

public static class PrototypeNotFoundException 

extends Exception { } 
public static class CannotCreateTrashException 

extends Exception { } 
private static List trashTypes = 

new ArrayList ( ) ; 
public static Trash factory (Messenger info) 

throws PrototypeNotFoundException, 

CannotCreateTrashException { 

for(int i = 0; i < trashTypes . size () ; i++) { 
// Somehow determine the new type 
// to create, and create one: 
Class tc = (Class) trashTypes . get (i) ; 
if (tc . getName ( ) . indexOf ( inf o . id) != -1) { 
try { 

// Get the dynamic constructor method 
// that takes a double argument: 
Constructor ctor = tc . getConstructor ( 

new Class []{ double. class }); 
// Call the constructor 
// to create a new object: 
return (Trash) ctor . newlnstance ( 

new Object [] {new Double (inf o . data) }) ; 
} catch (Exception ex) { 

ex . printStackTrace (System. err) ; 

throw new CannotCreateTrashException () ; 

} 

} 

} 

// Class was not in the list. Try to load it, 
// but it must be in your class path! 
try { 

System. out .println ( "Loading " + info. id); 
trashTypes . add (Class . f orName ( inf o . id) ) ; 
} catch (Exception e) { 



e.printStackTrace ( System. err) ; 

throw new PrototypeNotFoundException ( ) ; 

} 

// Loaded successfully. 

// Recursive call should work: 

return factory (info) ; 

} 

public static class Messenger { 
public String id; 
public double data; 

public Messenger (String name, double val) { 
id = name; 
data = val; 

} 

} 

} ///:- 

The basic Trash class and sumValue( ) remain as before, except that 
SumValue( ) is now made more generic by taking an Iterator as an 
argument. The rest of the cl ass supports the prototypi ng pattern. You f i rst 
see two inner classes (which are made static, so they are inner classes 
only for code organization purposes) describing exceptions that can 
occur. This isfollowed by an Array List called trashTypes, which is used 
to hold the Class references. 

In Trash .factory ( ), the String inside the M essenger object id (a different 
version of the Messenger class than that of the prior discussion) contains 
the type name of the Trash to be created; thisString iscompared to the 
C lass names i n the I ist. If there's a match, then that's the object to create. 
Of course, there are many ways to determine what object you want to 
make. This one is used so that information read in from afilecan be 
turned into objects. 

Once you've discovered which kind of Trash to create, then the reflection 
methods come i nto pi ay. The getC onstructor( ) method takes an 
argument that's an array of C lass references. This array represents the 
arguments, in their proper order, for the constructor that you're looking 
for. H ere, the array is dynamically created using the Java 1.1 array- 
creation syntax: 

new Class [] { double . class } 



This code assumes that every Trash type has a constructor that takes a 
double (and noti ce that double.class is distinct from Double.class). It's 
also possible, for a more flexible solution, to call getConstructors( ), 
which returns an array of the possible constructors. 

What comes back from getConstructor( ) is a reference to a Constructor 
object (part of java.lang. reflect). You call the constructor dynamically 
with the method newlnstance( ), which takes an array of Object 
containing the actual arguments. This array is again created using the 
Java 1.1 syntax: 

new Object [] {new Double (Messenger . data) } 

In this case, however, the double must be placed inside a wrapper class 
so that it can be part of this array of objects. The process of calling 
newlnstance( ) extracts the double, but you can see it is a bit confusing— 
an argument might be a double or a Double, but when you make the call 
you must always passin a Double. Fortunately, this issue exists only for 
the primitive types. 

Once you understand how to do it, the process of creati ng a new object 
given only a Class reference is remarkably simple. Reflection also allows 
you to call methods in this same dynamic fashion. 

Of cou rse, the appropri ate C I ass reference mi ght not be i n the trashTypes 
list. In this case, the return in the inner loop is never executed and you'll 
drop out at the end. Here, the program tries to rectify the situation by 
I oad i ng the C I ass object dynami cal I y and add i ng it to the trashTypes I i st. 
If it still can't be found something is really wrong, but if the load is 
successful then thefactory method is called recursively to try again. 

As you'll see, the beauty of this design is that this code doesn't need to be 
changed, regardless of thedifferent situations itwill be used in 
(assuming that all Trash subclasses contain a constructor that takes a 
single double argument). 



Trash subclasses 



To fit into the prototyping scheme, the only thing that's required of each 
new subclass of Trash is that it contai n a constructor that takes a double 
argument. Java reflection handles everything else. 

H ere are the different types of Trash, each i n thei r own f i le but part of the 
Trash package (again, to facilitate reusewithin the chapter): 

//: cl 2 : trash : Aluminum . java 

// The Aluminum class with prototyping. 

package cl2. trash; 

public class Aluminum extends Trash { 
private static double val = 1.67f; 
public Aluminum (double wt) { super(wt); } 
public double getValue() { return val; } 
public static void setValue (double newVal) { 
val = newVal ; 

} 

} ///:- 



//: cl2 : trash : Paper . java 

// The Paper class with prototyping. 

package cl2. trash; 

public class Paper extends Trash { 
private static double val = O.lOf; 
public Paper (double wt) { super (wt); } 
public double getValue() { return val; } 
public static void setValue (double newVal) { 
val = newVal; 

} 

} ///:- 



//: cl2 : trash : Glass . java 

// The Glass class with prototyping. 

package cl2. trash; 

public class Glass extends Trash { 
private static double val = 0.23f; 
public Glass (double wt) { super (wt); } 



public double getValue() { return val; } 
public static void setValue (double newVal) { 
val = newVal ; 

} 

} ///:- 



And here's a new type of Trash: 

//: cl2 : trash : Cardboard. java 

// The Cardboard class with prototyping. 

package cl2. trash; 

public class Cardboard extends Trash { 
private static double val = 0.23f; 
public Cardboard (double wt) { super (wt); } 
public double getValue() { return val; } 
public static void setValue (double newVal) { 
val = newVal; 

} 

} III:- 

You can see that, other than the constructor, there's nothing special about 
any of these classes. 

Parsing Trash from an external file 

The information aboutTrash objectswill be read from an outsidefile. 
The f i I e has al I of the necessary i nf ormati on about each pi ece of trash on a 
single line in the form Trash:w eight, such as: 

//:! cl2 : trash : Trash . dat 
cl2 . trash. Glass : 54 
cl2. trash. Paper : 22 
cl2. trash. Paper : 11 
cl2. trash. Glass:17 
cl2. trash. Aluminum : 8 9 
cl2. trash. Paper : 8 8 
cl2. trash. Aluminum : 7 6 
cl2. trash. Cardboard: 9 6 
cl2. trash. Aluminum : 2 5 
cl2. trash. Aluminum : 3 4 
cl2. trash. Glass:ll 



cl2. trash. Glass: 68 
cl2. trash. Glass:43 
cl2. trash. Aluminum : 2 7 
cl2. trash. Cardboard: 4 4 
cl2. trash. Aluminum : 1 8 
cl2 .trash. Paper: 91 
cl2. trash. Glass: 63 
cl2.trash.Glass:50 
cl2. trash. Glass:80 
cl2. trash. Aluminum : 8 1 
cl2. trash. Cardboard: 12 
cl2. trash. Glass:12 
cl2. trash. Glass:54 
cl2. trash. Aluminum : 3 6 
cl2. trash. Aluminum : 9 3 
cl2. trash. Glass: 93 
cl2. trash. Paper : 8 
cl2.trash.Glass:36 
cl2. trash. Glass:12 
cl2. trash. Glass: 60 
cl2. trash. Paper : 6 6 
cl2. trash. Aluminum : 3 6 
cl2. trash. Cardboard: 22 
///:- 



Note that the class path must be included when giving the class names, 
otherwise theclass will notbefound. 

To parse this, the line is read and theString method indexOf( ) produces 
the index of the':'. This is first used with theString method substring! ) 
to extract the name of the trash type, and next to get the wei ght that i s 
turned into a double with the static Double.valueOf( ) method. The 
tri m( ) method removes white space at both ends of a stri ng. 

The T rash parser i s pi aced i n a separate f i I e si nee i t w i 1 1 be reused 
throughout this chapter: 

//: cl2 : trash : ParseTrash . java 

// Parse file contents into Trash objects, 

// placing each into a Fillable holder. 

package cl2. trash; 

import java . util . * ; 

import java.io.*; 



public class ParseTrash { 
public static void 

fillBin (String filename, Fillable bin) { 
try { 

Buf f eredReader data = 
new Buf f eredReader ( 

new FileReader ( filename )) ; 
String buf; 

while ( (buf = data . readLine ( ) ) ! = null) { 
String type = buf . substring ( , 

buf . indexOf (':'))• trim ( ) ; 
double weight = Double . valueOf ( 

buf . substring (buf . indexOf (':' ) + 1) 
.trim ( ) ) . doubleValue ( ) ; 
bin . addTrash ( 
Trash . factory ( 

new Trash . Messenger (type, weight))); 

} 

data .close () ; 
} catch (Exception e) { 

e.printStackTrace ( System. err) ; 
// Change to an unchecked exception, for 
// ease of coding, but the unit test 
// mechanism will still be triggered: 
throw new RuntimeException ( ) ; 

} 

} 

// Special case to handle Collection: 
public static void 

fillBin ( String filename, Collection bin) { 

fillBin ( filename, new FillableCollection (bin) ) ; 

} 

} III:- 



In RecycleA.java, an Array List was used to hold theTrash objects. 
However, other types of containers can be used as well. To allow for this, 
the first version of fillBin( ) takes a reference to a Fillable, which is 
simply an interface that supports a method called addTrash( ): 

//: cl2 : trash : Fillable . java 

// Any object that can be filled with Trash, 
package cl2. trash; 



public interface Fillable { 

void addTrash (Trash t) ; 
} ///:- 



Anything that supports this interface can be used with fillBin. Of course, 
Collection doesn't implement Fillable, so itwon't work. Si nee Col lection 
is used in most of the examples, it makes sense to add a second 
overloaded fillBin( ) method that takes a Collection. Any Collection can 
then be used as a Fillable object using an adapter class: 

//: cl2: trash: Fill ableCollection. java 

// Adapter that makes a Collection Fillable. 

package cl2. trash; 

import java. util . * ; 

public class FillableCollection 
implements Fillable { 
private Collection c; 

public FillableCollection (Collection cc) { 
c = cc; 

} 

public void addTrash (Trash t) { 
c . add (t ) ; 

} 

} ///:- 

You can see that the only job of this class is to connect Fillable s 
addTrash( ) method to Collection's add( ). With this class in hand, the 
overloaded fillBin( ) method can be used with a Collection in 
ParseT rash .java: 



public static void 
fillBin (String filename, 
fillBin ( filename, new 

} 



Collection bin) { 
FillableCollection (bin) ) ; 



This approach works for any container class that's used frequently. 
Alternatively, the container class can provideitsown adapter that 
implements Fillable. (You'll see this later, in DynaT rash .java.) 



Recycling with prototyping 

Now you can seethe revised version of RecycleA.java using the 
prototypi ng techni que: 

//: cl2 : recycleap : RecycleAP . java 

// Recycling with RTTI and Prototypes. 

import cl2 . trash . * ; 

import java . util . * ; 

import com . bruceeckel . test .* ; 

public class RecycleAP extends UnitTest { 
Collection 

bin = new ArrayList ( ) , 

glassBin = new ArrayList (), 

paperBin = new ArrayList (), 

alBin = new ArrayList () ; 
public RecycleAP () { 

// Fill up the Trash bin: 

Parser rash.fillBin ( 

". ./trash/Trash. dat", bin); 

} 

public void test() { 

Iterator sorter = bin . iterator () ; 
// Sort the Trash: 
while ( sorter . hasNext () ) { 
Object t = sorter . next () ; 
// RTTI to show class membership: 
if (t instanceof Aluminum) 

alBin. add (t) ; 
if (t instanceof Paper) 

paperBin . add (t ) ; 
if (t instanceof Glass) 
glassBin . add (t ) ; 

} 

Trash . sumValue (alBin . iterator ( ) ) ; 
Trash . sumValue (paperBin . iterator ( ) ) ; 
Trash . sumValue (glassBin . iterator ( ) ) ; 
Trash . sumValue (bin . iterator ( ) ) ; 

} 

public static void main (String args [ ] ) { 
new RecycleAP ( ) . test ( ) ; 

} 

} ///:~ 



All of the Trash objects, as well astheParseTrash and support classes, 
are now part of the package cl2.trash, so they are simply imported. 

The process of openi ng the data f i I e contai ni ng Trash descri pti ons and 
the parsing of that file have been wrapped into the static method 
ParseTrash.fillBin( ), so now it's no longer a part of our design focus. 
You will see that throughout the rest of the chapter, no matter what new 
classes are added, ParseT rash .fill Bin ( ) will continue to work without 
change, which indicates a good design. 

In terms of object creation, this design does indeed severely localizethe 
changes you need to make to add a new type to the system. However, 
there's a significant problem i n the use of RTTI that shows up clearly 
here. The program seems to run fine, and yet it never detects any 
cardboard, even though there is cardboard in the list! This happens 
because of the use of RTTI , which looks for only the types that you tell it to 
look for. The cluethat RTTI isbeing misused isthat every typein the 
system is being tested, rather than asingletype or subset of types. Asyou 
will seelater, there are ways to use polymorphism instead when you're 
testi ng for every type. But if you use RTTI a lot in this fashion, and you 
add a new type to your system, you can easi ly forget to make the 
necessary changes in your program and produce a d iff i cult-to-find bug. 
Soit'sworth trying to eliminate RTTI inthiscase, not just for aesthetic 
reasons— it produces more maintainable code. 



With creation out of the way, it's time to tackle the remainder of the 
design: where the classes are used. Si nee it's the act of sorting into bins 
that's particularly ugly and exposed, why not take that process and hide 
it inside a class? This is the principle of "If you must do something ugly, 
at least localizethe ugliness inside a class." It looks like this: 
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Aluminum ArrayList 








ArrayList of 
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Glass ArrayList 







TheTrashSorter object initialization must now be changed whenever a 
new type of Trash is added to the mod el. You could imagine that the 
TrashSorter class might look something I ike this: 

class TrashSorter extends ArrayList { 
void sort (Trash t) {/*...*/} 

} 

That is, TrashSorter is an ArrayList of references to Array Lists of Trash 

references, and with add( ) you can install another one, likeso: 

TrashSorter ts = new TrashSorter () ; 
ts. add (new ArrayList ()) ; 

Now, however, sort( ) becomes a problem. How does the statically- coded 
method deal with the fact that a new type has been added? To solve this, 
the type i nf ormati on must be removed from sort( ) so that al I it needs to 
do i s cal I a generic method that takes care of the details of type. This, of 
course, isanotherway to describea dynamically-bound method. So 
sort( ) will simply movethrough the sequence and call a dynamically- 
bound method for each ArrayList. Since thejob of this method isto grab 
the pieces of trash it is interested in, it's called grab(Trash). The structure 
now looks I ike: 



Aluminum ArrayList 



TrashSorter 



ArrayList of u 
Trash Bins n 



boolean grab(Trash) 



Paper ArrayList 



boolean grab(Trash) 



Glass ArrayList 



boolean grab(Trash) 



TrashSorter needs to call each grab( ) method and get a different result 
depending on what type of Trash the current Array List is hoi ding. That 
is, each ArrayList must be aware of the type it holds. The classic 
approach to this problem isto create a base "Trash bin" class and inherit 
a new derived class for each different type you want to hold. If Java had a 
parameterized type mechanism that would probably be the most 
straightforward approach. But rather than hand-coding all the classes 
that such a mechanism should be building for us, further observation can 
produce a better approach. 

A basic OOP design principleis"Usedata members for variation in state, 
use polymorphism for variation in behavior." Your first thought might be 
that the grab( ) method certainly behaves differently for an ArrayList 
that holds Paper than for one that holds G lass. But what it does is strictly 
dependent on the type, and nothing else. This could be i nterpreted as a 
different state, and sincejava has a class to represent type (Class) this can 
be used to determinethe type of Trash a particular Tbin will hold. 

The constructor for thisTbin requires that you hand it the Class of your 
choi ce. Thistells the A rray L i st what type i t i s supposed to hoi d . Then the 
grab( ) method usesClass BinType and RTTI to see if the Trash object 
you've handed it matches the type it's supposed to grab. 

Here is the whole program. The commented numbers (e.g., (*1*) ) mark 
sections that will bedescribed foil owing the code. 



//: cl2 : recycleb : RecycleB . java 

// Adding more objects to the recycling problem, 
import cl2 . trash . * ; 



import java . util . * ; 

import com . bruceeckel . test .* ; 



// A container that admits only the right type 
// of Trash (established in the constructor) : 
class Tbin implements Fillable { 

private Collection list = new ArrayList (); 

private Class type; 

public Tbin (Class binType) { type = binType; } 
public void addTrash (Trash t) { list . add (t ) ; } 
public boolean grab (Trash t) { 

// Comparing class types: 

if (t . getClass (). equals (type) ) { 
list . add (t ) ; 

return true; // Object grabbed 

} 

return false; // Object not grabbed 

} 

public Iterator iterator () { 
return list . iterator () ; 

} 



class TbinList extends ArrayList { //(*1*) 
boolean sort (Trash t) { 
Iterator e = iterator (); 
while (e . hasNext () ) { 

Tbin bin = (Tbin) e . next () ; 
if (bin . grab (t ) ) return true; 

} 

return false; // bin not found for t 

} 

void sortBin(Tbin bin) { // (*2*) 
Iterator e = bin . iterator () ; 
while (e . hasNext ( ) ) 

if ( ! sort ( (Trash) e . next ( ) ) ) 

System . out . println ( "Bin not found"); 

} 

} 

public class RecycleB extends UnitTest { 
Tbin bin = new Tbin (Trash . class ) ; 
TbinList trashBins = new TbinList (); 
public RecycleB () { 



// Fill up the Trash bin: 
ParseTrash.fillBin ( 

". ./trash/Trash. dat", bin); 
trashBins . add (new Tbin (Aluminum. class) ) ; 
trashBins . add (new Tbin (Paper. class) ) ; 
trashBins . add (new Tbin (Glass . class) ) ; 
// add one line here: (*3*) 
trashBins . add (new Tbin (Cardboard. class) ) ; 

} 

public void test() { 

trashBins . sortBin (bin) ; // (*4*) 
Iterator e = trashBins . iterator () ; 
while (e . hasNext () ) { 

Tbin b = (Tbin) e . next () ; 

Trash . sumValue (b . iterator ( ) ) ; 

} 

Trash . sumValue (bin . iterator ( ) ) ; 

} 

public static void main (String args [ ] ) { 
new RecycleB ( ) . test ( ) ; 

} 

///:- 



1. TbinListholdsasetof Tbin references, sothatsort( ) can iterate 
through theTbins when it's looking for a match for theTrash 

object you've handed it. 

2. sortBin( ) allows you to pass an entireTbin in, and it moves 
through theTbin, picks out each piece of Trash, and sorts itinto 
the appropriate specific Tbin. N oti ce th e gen eri city of this code: it 
doesn't change at all if new types are added. If the bulk of your 
code doesn't need changing when a new type is added (or some 
other change occurs) then you have an easily-extensible system. 

3. N ow you can see how easy it is to add a new type. Few I i nes must 
be changed to support the addition. If it's really important, you 
can squeeze out even more by further manipulating the design. 

4. One method cal I causes the contents of bi n to be sorted i nto the 
respective specifically-typed bins. 



Multiple dispatching 

The above design iscertainly satisfactory. Adding new types to the 
system consists of adding or modifying distinct classes without causing 
code changes to be propagated throughout the system. In addition, RTTI 
is not "misused" asitwasin RecycleA.java. However, it's possibletogo 
one step further and take a purist viewpoint about RTTI and say that it 
should be eliminated altogether from the operation of sorting the trash 
into bins. 

To accomplish this, you must first take the perspective that all type- 
dependent activities— such asdetecting the type of a piece of trash and 
putting it into the appropriate bin— should be control led through 
polymorphism and dynamic binding. 

The previous examples first sorted by type, then acted on sequences of 
elements that were all of a particular type. But whenever you find 
yourself picking out particular types, stop and think. The whole idea of 
polymorphism (dynamically-bound method calls) isto handletype- 
specific information for you. So why are you hunting for types? 

The answer is something you probably don't think about: Java performs 
only single dispatching. That is, if you are performing an operation on 
more than one object whose type i s unknown, J ava wi 1 1 i nvoke the 
dynamic binding mechanism on only one of those types. This doesn't 
solve the problem, so you end up detecting some types manually and 
effectively producing your own dynamic binding behavior. 

Thesolution is called multipledispatching, which means setting up a 
configuration such that a single method call produces more than one 
dynamic method call and thus determines more than onetypein the 
process. To get this effect, you need to work with more than onetype 
hierarchy: you'll need a type hierarchy for each dispatch. The foil owing 
example works with two hierarchies: the existing Trash family and a 
hierarchy of the types of trash bins that the trash will be placed into. This 
second hierarchy isn't always obvious and in this case it needed to be 
created in order to produce multiple dispatching (in this case there will 
be only two dispatches, which is referred to as double dispatching). 



Implementing the double dispatch 

Remember that polymorphism can occur only via method calls, so if you 
want double dispatching to occur, there must be two method calls: one 
used to determine thetypewithin each hierarchy. In theTrash hierarchy 
therewill bea new method called addToBin( ), which takes an argument 
of an array of TypedBin. It uses this array to step through and try to add 
itself to the appropriate bin, and this is where you'll see the double 
dispatch. 



Trash 

addToBin(TypedBin[]) 



Aluminum 


Paper 


Glass 


Cardboard 


addToBin(TypedBin[]) 


addToBin(TypedBin[]) 


addToBin(TypedBin[]) 


addToBin (Typed Bint ]) 



TypedBin 

add( Aluminum) 
add( Paper) 
add(Glass) 
add(Cardboard) 



AluminumBin 


PaperBin 


GlassBin 


CardboardBin 


add(Aluminum) 


add( Paper) 


add(Glass) 


add(Cardboard) 



The new hierarchy is TypedBin, and it contains its own method called 
add() that is also used polymorphically. But here's an additional twist: 
add( ) is overloaded to take arguments of the different types of trash. So an 
essential part of thedoubledispatching scheme also involves 
overloading. 

Redesigning the program produces a dilemma: it's now necessary for the 
base class Trash to contain an addToBin ( ) method. One approach is to 
copy al I of the code and change the base cl ass. A nother approach, whi ch 
you can take when you don't have control of the source code, is to put the 
addToBin( ) method into an interface, leaveTrash alone, and inherit 



new specific types of Aluminum, Paper, Glass, and Cardboard. This is 
the approach that will be taken here. 

M ost of the cl asses i n thi s desi gn must be public, so they are pi aced i n 
thei r own f i I es. H ere's the i nterface: 

// : cl2 : doubledispatch : TypedBinMember . java 
// An interface for adding the double 
// dispatching method to the trash hierarchy 
// without modifying the original hierarchy. 

interface TypedBinMember { 
// The new method: 
boolean addToBin (TypedBin [ ] tb) ; 

} ///:- 

In each particular subtype of Aluminum, Paper, Glass, and Cardboard, 
theaddToBin( ) method in the interface Typed BinM ember is 

implemented, butitlooks I ike the code is exactly the same in each case: 

// : cl 2 : doubledispatch : DD Aluminum . java 
// Aluminum for double dispatching, 
import cl2 . trash . * ; 

public class DDAluminum extends Aluminum 
implements TypedBinMember { 
public DDAluminum (double wt) { super (wt); } 
public boolean addToBin (TypedBin [ ] tb) { 
for(int i = 0; i < tb. length; i++) 
if (tb [i] .add (this) ) 
return true; 
return false; 

} 

} ///:- 

// : cl 2 : doubledispatch : DDPaper . java 
// Paper for double dispatching, 
import c 12. trash. *; 

public class DDPaper extends Paper 
implements TypedBinMember { 
public DDPaper (double wt) { super (wt); } 
public boolean addToBin (TypedBin [ ] tb) { 



for(int i = 0; i < tb. length; i++) 
if (tb [i] .add (this) ) 
return true; 
return false; 

} 

} ///:- 

// : cl2 : do uble dispatch : DDG1 ass . java 
// Glass for double dispatching, 
import c 12. trash.*; 

public class DDGlass extends Glass 
implements TypedBinMember { 
public DDGlass (double wt) { super (wt); } 
public boolean addToBin (TypedBin [ ] tb) { 
for(int i = 0; i < tb. length; i++) 
if (tb [i] .add (this) ) 
return true; 
return false; 

} 

} ///:- 

// : cl2 : do uble dispatch : DDCardboard. java 
// Cardboard for double dispatching, 
import c 12. trash.*; 

public class DDCardboard extends Cardboard 
implements TypedBinMember { 
public DDCardboard (double wt) { super (wt); } 
public boolean addToBin (TypedBin [ ] tb) { 
for(int i = 0; i < tb. length; i++) 
if (tb [i] .add (this) ) 
return true; 
return false; 

} 

} ///:- 

Thecodein each addToBin( ) calls add( )for each TypedBin object in the 
array. But notice the argument: this. The type of this is different for each 
subclass of Trash, so the code is different. (Although thiscodewill 
benefit if a parameterized type mechanism is ever added to Java.) So this 



i s the f i rst part of the d ou bl e d i spatch , because once you ' re i nsi d e th i s 
method you know you'reAluminum, or Paper, etc. During the call to 
add( ), this information is passed via the type of this. The compiler 
resolves the call to the proper overloaded version of add( ). Butsincetb[i] 
produces a reference to the base typeTypedBin, this call will end up 
calling a different method depending on the type of TypedBin that's 
currently selected. That is the second dispatch. 

H ere's the base cl ass for Typed Bi n : 

// : cl2 : doubledispatch : TypedBin . java 
// A container for the second dispatch, 
import cl2 . trash . * ; 
import java. util . *; 

public abstract class TypedBin { 
Collection c = new ArrayList ( ) ; 
protected boolean addlt (Trash t) { 

c.add(t) ; 

return true; 

} 

public Iterator iterator () { 
return c . iterator () ; 

} 

public boolean add (DDAluminum a) { 
return false; 

} 

public boolean add(DDPaper a) { 
return false; 

} 

public boolean add(DDGlass a) { 
return false; 

} 

public boolean add (DDCardboard a) { 
return false; 

} 

} ///:- 



You can see that the overloaded add( ) methods all return false. If the 
method is not overloaded in a derived class, it will continueto return 
false, and the caller (addToBin( ), in this case) will assume that the 



currentTrash object has not been added successfully to a container, and 
conti nue searchi ng for the ri ght contai ner. 

In each of the subclasses of TypedBin, only one overloaded method is 
overridden, according to the type of bin that's being created. For 
example, CardboardBin overrides add (DD Cardboard). The overridden 
method addsthetrash object to its contai ner and returns true, while all 
the rest of theadd( ) methods in CardboardBin conti nue to return false, 
si nee they haven't been overridden. This is another casein which a 
parameterized type mechanism injava would allow automatic 
generation of code. (With C++ tern plates, you wouldn't haveto explicitly 
write the subclasses or placetheaddToBin( ) method inTrash.) 

Since for this example the trash types have been customized and placed 
in a different directory, you'll need a different trash data fileto make it 
work. Here's a possibleDDTrash.dat: 

//: ! cl2 :doubledispatch: DDTrash.dat 

DDGlass : 54 

DDPaper : 22 

DDPaper : 11 

DDGlass : 17 

DDAluminum: 8 9 

DDPaper: 88 

DDAluminum : 7 6 

DDCardboard: 96 

DDAluminum : 2 5 

DDAluminum: 3 4 

DDGlass : 11 

DDGlass : 68 

DDGlass : 43 

DDAluminum: 27 

DDCardboard: 44 

DDAluminum: 18 

DDPaper: 91 

DDGlass : 63 

DDGlass : 50 

DDGlass : 80 

DDAluminum: 81 

DDCardboard: 12 

DDGlass : 12 

DDGlass : 54 

DDAluminum : 3 6 



DDAluminum: 9 3 
DDGlass : 93 
DDPaper : 80 
DDGlass : 36 
DDGlass : 12 
DDGlass : 60 
DDPaper: 66 
DDAluminum : 3 6 
DDCardboard: 22 
///:- 



H ere's the rest of the program: 

// : cl2 : do uble dispatch : DoubleDispatch . java 

// Using multiple dispatching to handle more 

// than one unknown type during a method call. 

import cl2 . trash . * ; 

import java . util . * ; 

import com . bruceeckel . test .* ; 

class AluminumBin extends TypedBin { 
public boolean add (DDAluminum a) { 
return addlt (a) ; 




class PaperBin extends TypedBin { 
public boolean add (DDPaper a) { 
return addlt (a) ; 




class GlassBin extends TypedBin { 
public boolean add (DDGlass a) { 
return addlt (a) ; 




class CardboardBin extends TypedBin { 
public boolean add (DDCardboard a) { 
return addlt (a) ; 




class TrashBinSet { 

private TypedBin [ ] binSet = { 
new AluminumBin ( ) , 
new PaperBin(), 
new GlassBin ( ) , 
new CardboardBin ( ) 

}; 

public void sortlntoBins (Collection bin) { 
Iterator e = bin . iterator () ; 
while (e . hasNext () ) { 
TypedBinMember t = 

(TypedBinMember ) e . next ( ) ; 
if ( ! t . addToBin (binSet) ) 

System. err .println ( "Couldn ' t add " + t) ; 

} 

} 

public TypedBin [] binSet () { return binSet; } 



public class DoubleDispatch extends UnitTest { 
Collection bin = new ArrayList ( ) ; 
TrashBinSet bins = new TrashBinSet () ; 
public DoubleDispatch ( ) { 

// ParseTrash still works, without changes: 
ParseTrash. fillBin ("DDTrash.dat", bin) ; 

} 

public void test() { 

// Sort from the master bin into 

// the individually-typed bins: 

bins . sortlntoBins (bin) ; 

TypedBin [] tb = bins . binSet () ; 

// Perform sumValue for each bin... 

for(int i = 0; i < tb. length; i++) 

Trash . sumValue (tb [ i ] . c . iterator ( ) ) ; 
// ... and for the master bin 
Trash . sumValue (bin . iterator ( ) ) ; 

} 

public static void main (String args [ ] ) { 
new DoubleDispatch (). test () ; 

} 

} ///:- 



Trash BinSet encapsulates all of the different types of TypedBins, along 
with thesortlntoBins( ) method, which is where all the double 
dispatching takes place. You can seethatoncethestructureissetup, 
sorting into the various Typed Bins is remarkably easy. In addition, the 
efficiency of two dynamic method calls is probably better than any other 
way you could sort. 

N oti ce the ease of use of thi s system i n mai n( ), as wel I as the compl ete 
i ndependence of any specif i c type i nformati on wi thi n mai n( ). A 1 1 other 
methods that talk only to the Trash base-cl ass interface will be equally 
invulnerable to changes in Trash types. 

The changes necessary to add a new type are relatively isolated: you 
modify TypedBin, inherit the new type of Trash with itsaddToBin( ) 
method, then inherit a new TypedBin (this is really just a copy and 
simpleedit), and finally add a new type into the aggregate initialization 
for Trash BinSet. 

The Visitor pattern 

Now consider applying a design pattern that has an entirely different 
goal to the trash sorting problem. 

For this pattern, we are no longer concerned with optimizing the 
addition of new types of Trash to the system. Indeed, this pattern makes 
adding a new type of Trash more complicated. The assumption isthat 
you have a primary class hierarchy that is fixed; perhaps it's from 
another vendor and you can't make changes to that hierarchy. However, 
you'd liketo add new polymorphic methods to that hierarchy, which 
means that normally you'd have to add something to the base class 
i nterface. So the di I emma is that you need to add methods to the base 
class, but you can'ttouch the base class. How do you get around this? 

Thedesign pattern that solves this kind of problem is called a "visitor" 
(thefinal onein theDesign Patterns book), and itbuildson thedouble 
dispatching scheme shown in the last section. 

The visitor pattern al lows you to extend the i nterface of the pri mary type 
by creating a separate class hierarchy of type Visitor to virtualizethe 
operations performed upon the primary type. The objects of the pri mary 



type simply "accept" the visitor, then call the visitor's dynamically- 
bound method. It looks I ike this: 



Trash 



accept(Visitor) 

A 















Alum 


inum 




Paper 




Glass 


accept(Visitor v) { 
v.visit(this); 

} 




accept(Visitor v) { 
v.visit(this); 

} 




accept(Visitor v) { 
v.visit(this); 

} 



Visitor 

visit( Aluminum) 
visit( Paper) 
visit(Glass) 









PriceVisitor 




WeightVisitor 


Etc. 


visit( Aluminum) { 
// Perform Aluminum- 
// specific work 

} 

visit(Paper) { 
// Perform Paper- 
// specific work 

} 

visit(Glass) { 
// Perform Glass- 
// specific work 

} 


visit( Aluminum) { 
// Perform Aluminum- 
// specific work 

} 

visit(Paper) { 
// Perform Paper- 
// specific work 

} 

visit(Glass) { 
// Perform Glass- 
// specific work 

} 





Now, if v is a Visitable reference to an Aluminum object, the code: 

PriceVisitor pv = new PriceVisitor () ; 
v . accept (pv) ; 



uses double dispatching to cause two polymorphic method calls: thefirst 
oneto select Aluminum's version of accept( ), and thesecond onewithin 
accept( ) when the specific version of visit( ) is called dynamically using 
the base-class Visitor reference v. 

This configuration means that new functionality can be added to the 
system in theform of new subclasses of Visitor. TheTrash hierarchy 
doesn't need to be touched. This is the prime benefit of the visitor 
pattern: you can add new polymorphic functionality to a class hierarchy 
without touching that hierarchy (once the accept( ) methods have been 
installed). Note that the benefit is helpful here but not exactly what we 
started out to accomplish, so at first blush you might decide that this isn't 
thedesired solution. 

But look at one thing that's been accomplished: the visitor solution 
avoids sorting from the master Trash sequence into individual typed 
sequences. Thus, you can leave everything in the singlemaster sequence 
and si mply pass through that sequence using the appropriate visitor to 
accomplish the goal. Although this behavior seems to be a side effect of 
visitor, it does give us what we want (avoiding RTTI). 

Thedoubledispatching in the visitor pattern takes care of determining 
both the type of Trash and the type of Visitor. In the foil owing example, 
there are two implementations of Visitor: PriceVisitorto both determine 
and sum the price, and WeightVisitorto keep track of the weights. 

You can see all of this implemented in the new, improved version of the 
recycling program. 

Aswith DoubleDispatch.java, theTrash class is left alone and anew 
i nterface i s created to ad d the accept( ) method : 

// : cl2 : trashvisitor : Visitable . java 

// An interface to add visitor functionality 

// to the Trash hierarchy without 

// modifying the base class. 

import cl2 . trash . * ; 

interface Visitable { 
// The new method: 
void accept (Visitor v) ; 



} ///:- 



Si nee there's nothing concrete in the Visitor base class, it can be created 
as an interface: 

// : cl2 : trashvisitor : Visitor . java 
// The base interface for visitors, 
import cl2 . trash . * ; 

interface Visitor { 

void visit (Aluminum a) ; 

void visit (Paper p) ; 

void visit (Glass g) ; 

void visit (Cardboard c) ; 
} III:- 



A Reflective Decorator 

At this point, you could follow the same approach that was used for 
double dispatching and create new subtypes of Aluminum, Paper, Glass, 
and Cardboard that implement the accept( ) method. For example, the 
new Visitable Aluminum would look likethis: 

// : cl2 : trashvisitor : VAluminum. java 
// Taking the previous approach of creating a 
// specialized Aluminum for the visitor pattern, 
import cl2 . trash . * ; 

public class VAluminum extends Aluminum 
implements Visitable { 
public VAluminum (double wt) { super (wt); } 
public void accept (Visitor v) { 
v. visit (this) ; 

} 

} III:- 

However, we seem to be encountering an "explosion of interfaces:" basic 
Trash, special versions for double dispatching, and now more special 
versions for visitor. Of course, this "explosion of interfaces" is arbitrary- 
one could simply put the additional methods in theTrash class. If we 



ignore that we can instead see an opportunity to use the Decorator 
pattern : i t seems I i ke i t shou I d be possi bl e to create a D ecorator that can be 
wrapped around an ordinary Trash object and will produce the same 
interface as Trash and add the extra accept( ) method. In fact, it's a 
perfect exampl e of the val ue of D ecorator . 

The doubl e dispatch creates a probl em, however. Si nee it relies on 
overloading of both accept( ) and visit( ), it would seem to require 
specialized codefor each different version of theaccept( ) method. With 
C++ templates, thiswould be fairly easy to accomplish (si nee templates 
automatically generate type-specialized code) butjava has no such 
mechanism— at least it does not appear to. However, reflection allows 
you to determine type information at run time, and it turns out to solve 
many probl ems that would seem to requireternplates(albeitnotas 
si mply). H ere's the decorator that does the tri c\M 

I/: cl2 : trashvisitor : VisitableDecorator . java 

// A decorator that adapts the generic Trash 

// classes to the visitor pattern. 

import cl2 . trash . * ; 

import java . lang . reflect . * ; 

public class VisitableDecorator 
extends Trash implements Visitable { 
private Trash delegate; 
private Method dispatch; 
public VisitableDecorator (Trash t) { 
delegate = t; 
try { 

dispatch = Visitor . class . getMethod ( 
"visit", new Class [] { t . getClass ( ) } 

) ; 

} catch (Exception ex) { 
ex . printStackTrace () ; 

} 

} 

public double getValue() { 
return delegate . getValue () ; 

} 



2 This was a solution created byJaroslavTulach in a design patterns class that I 
gave in Prague. 



public double getWeight() { 
return delegate . getWeight () ; 

} 

public void accept (Visitor v) { 
try { 

dispatch . invoke (v, new Ob ject []{ delegate }) ; 
} catch (Exception ex) { 
ex . printStackTrace () ; 

} 

} 

} ///:- 

[[ Description of Reflection use ]] 

The only other tool weneed isanew type of Fill able adapter that 
automatical I y decorates the objects as they are bei ng created from the 
original Trash.dat file. But this might as well be a decorator itself, 
decorating any kind of Fillable: 

// : cl2 : trashvisitor : FillableVisitor . java 
// Adapter Decorator that adds the visitable 
// decorator as the Trash objects are 
// being created, 
import cl2 . trash . * ; 
import java . util . * ; 

public class FillableVisitor 

implements Fillable { 
private Fillable re- 
public FillableVisitor (Fillable ff) { f = ff; } 
public void addTrash (Trash t) { 

f . addTrash (new VisitableDecorator (t ) ) ; 

} 

} ///:- 

Now you can wrap it around any kind of existing Fillable, or any new 
ones that haven't yet been created. 

The rest of the program creates specific Visitor types and sends them 
through a single list of Trash objects: 

// : cl2 : trashvisitor : Trashvisitor . java 

// The "visitor" pattern with VisitableDecorators . 



import 
import 
import 



cl2 . trash . * ; 
java . util . * ; 
com . bruceeckel . test . * ; 



// Specific group of algorithms packaged 
// in each implementation of Visitor: 
class PriceVisitor implements Visitor { 
private double alSum; // Aluminum 
private double pSum; // Paper 
private double gSum; // Glass 
private double cSum; // Cardboard 
public void visit (Aluminum al) { 

double v = al . getWeight ( ) * al.getValue 
System. out .print In ( 

"value of Aluminum= " + v) ; 
alSum += v; 

} 

public void visit (Paper p) { 

double v = p . getWeight ( ) * p.getValue() 
System . out . print In ( 

"value of Paper= " + v) ; 
pSum += v; 

} 

public void visit (Glass g) { 

double v = g . getWeight ( ) * g.getValue() 
System . out . print In ( 

"value of Glass= " + v) ; 
gSum += v; 

} 

public void visit (Cardboard c) { 

double v = c . getWeight ( ) * c.getValue() 
System . out . print In ( 

"value of Cardboard = " + v) ; 
cSum += v; 

} 

void total ( ) { 

System. out .print In ( 

"Total Aluminum: $" + alSum + "\n" + 
"Total Paper: $" + pSum + "\n" + 
"Total Glass: $" + gSum + "\n" + 
"Total Cardboard: $" + cSum) ; 



class Weight Visitor implements Visitor { 
private double alSum; // Aluminum 
private double pSum; // Paper 
private double gSum; // Glass 
private double cSum; // Cardboard 
public void visit (Aluminum al) { 
alSum += al . getWeight () ; 

System . out . println ( "weight of Aluminum = 
+ al .getWeight ( ) ) ; 

} 

public void visit (Paper p) { 
pSum += p . getWeight () ; 

System . out . println ( "weight of Paper = " 
+ p . getWeight ( ) ) ; 

} 

public void visit (Glass g) { 
gSum += g . getWeight () ; 

System . out . println ( "weight of Glass = " 
+ g. getWeight ( ) ) ; 

} 

public void visit (Cardboard c) { 
cSum += c . getWeight () ; 

System . out . println ( "weight of Cardboard = 
+ c . getWeight ( ) ) ; 

} 

void total ( ) { 

System. out .println ( "Total weight Aluminum 
+ alSum) ; 

System. out .println ( "Total weight Paper:" 
+ pSum) ; 

System. out .println ( "Total weight Glass:" 
+ gSum) ; 

System. out .println ( "Total weight Cardboar 
+ cSum) ; 



public class TrashVisitor extends UnitTest { 
Collection bin = new ArrayList ( ) ; 
PriceVisitor pv = new PriceVisitor () ; 
WeightVisitor wv = new WeightVisitor () ; 
public TrashVisitor ( ) { 

ParseTrash . f illBin ( " . . /t rash/ Trash . dat " , 
new FillableVisitor ( 



new FillableCollection (bin) ) ) ; 

} 

public void test() { 

Iterator it = bin . iterator () ; 
while (it .hasNext () ) { 

Visitable v = (Visitable) it . next () ; 
v . accept (pv) ; 
v . accept (wv) ; 

} 

pv .total ( ) ; 
wv .total ( ) ; 

} 

public static void main (String args [ ] ) { 
new TrashVisitor ( ) . test ( ) ; 

} 

} ///:~ 

InTestO, note how visitability is added by simply creating a different 
kind of bin using the decorator. Also notice that the FillableCollection 
adapter has the appearance of being used asa decorator (for Array List) 
in this situation. However, it completely changes the interface of the 
ArrayList, whereas the definition of Decorator is that the interface of the 
decorated class must still be there after decoration. 

Note that the shape of the client code(shown in the Test class) has 
changed again, from the original approaches to the problem. Now there's 
only asingleTrash bin. The two Visitor objects are accepted into every 
element in the sequence, and they perform their operations. The visitors 
keep thei r own i nternal data to tal ly the total wei ghts and pri ces. 

Finally, there's no run time type identification other than the inevitable 
casttoTrash when pulling things out of the sequence. This, too, could be 
eliminated with the implementation of parameterized types in Java. 

O ne w ay you can d i sti ngu i sh th i s sol uti on from the d ou bl e d i spatch i ng 
solution described previously isto note that, in the double dispatching 
solution, only one of the overloaded methods, add( ), was overridden 
when each subclass was created, whilehereeach one of the overloaded 
visit( ) methods is overridden in every subclass of Visitor. 



More coupling? 

There's a lot more code here, and there's definite coupling between the 
Trash hierarchy and the Visitor hierarchy. However, there's also high 
cohesion within the respective sets of classes: they each do only one thing 
(Trash describes Trash, while Visitor describes actions performed on 
Trash), which is an indicator of a good design. Of course, in this case it 
works well only if you're adding new Visitors, but it gets in the way 
when you add new types of Trash. 

Low coupling between classes and high cohesion within a class is 
definitely an important design goal. Applied mindlessly, though, it can 
prevent you from achieving a more elegant design. It seems that some 
classes inevitably have a certai n i nti macy with each other. These often 
occur in pairs that could perhaps be called couplets; for example, 
containers and iterators. The Trash-Visitor pair above appears to be 
another such couplet. 

RTTI considered harmful? 

Various designs in this chapter attempt to remove RTTI, which might 
giveyou theimpression that it's "considered harmful" (the 
condemnation used for poor, ill-fated goto, which was thus never put 
i nto J ava) . Th i s i sn 't tru e; i t i s the m i su se of RTTI that i s the probl em. The 
reason our designs removed RTTI is because the misapplication of that 
feature prevented extensibility, while the stated goal was to beableto 
add a new type to the system with as little impact on surrounding code 
as possible. Since RTTI is often misused by having it look for every single 
type in your system, it causes code to be non-extensible: when you add a 
new type, you have to go hunting for all the code in which RTTI is used, 
and if you miss any you won't get help from the compiler. 

However, RTTI d oesn 't automati cal I y create n on- extensible code. Let's 
revisit the trash recycler once more. This time, a new tool will be 
introduced, which I call a TypeMap. It contains a Hash Map that holds 
ArrayLists, but the interface is simple: you can add( ) a new object, and 
you can get( ) an Array List containing all the objects of a particular type. 
The keys for the contained Hash Map are the types in the associated 
ArrayList. The beauty of this design (suggested by Larry O'Brien) isthat 



theTypeM ap dynamically adds a new pair whenever it encounters a 
new type, so whenever you add a new type to the system (even if you 
add the new type at run time), it adapts. 

Our example will again build on the structure of the Trash types in 
package cl2.T rash (and theTrash.dat file used there can be used here 
without change): 

//: cl2 : dynatrash : DynaTrash . java 

// Using a Map of Lists and RTTI 

// to automatically sort trash into 

// ArrayLists. This solution, despite the 

// use of RTTI, is extensible. 

import cl2 . trash . * ; 

import java. util . *; 

import com . bruceeckel . test .* ; 

// Generic TypeMap works in any situation: 
class TypeMap { 

private Map t = new HashMapO; 
public void add (Object o) { 
Class type = o . getClass ( ) ; 
if (t . containsKey (type) ) 

( (List ) t . get (type) ) . add (o ) ; 
else { 

List v = new ArrayList ( ) ; 

v . add ( o ) ; 

t . put (type, v) ; 

} 

} 

public List get (Class type) { 
return (List ) t . get (type) ; 

} 

public Iterator keys() { 

return t . keySet (). iterator () ; 




// Adapter class to allow callbacks 
// from ParseTrash . f illBin ( ) : 
class TypeMapAdapter implements Fillable { 
TypeMap map; 

public TypeMapAdapter (TypeMap tm) { map = tm; } 
public void addTrash (Trash t) { map. add (t); } 



} 



public class DynaTrash extends UnitTest { 
TypeMap bin = new TypeMap () ; 
public DynaTrash () { 

ParseTrash . f illBin ( " . . /t rash/ Trash . dat " , 
new TypeMapAdapter (bin) ) ; 

} 

public void test() { 

Iterator keys = bin. keys (); 
while (keys . hasNext ( ) ) 
Trash. sumValue ( 

bin . get ( (Class ) keys . next ( ) ) . iterator ( ) ) ; 

} 

public static void main (String args [ ] ) { 
new DynaTrash (). test () ; 

} 

} ///:~ 



Although powerful, thedefinition for TypeM ap issimple. Itcontainsa 
Hash Map, and theadd( ) method does most of the work. When you 
add( ) a new object, the reference for the C lass object for that type is 
extracted. This is used as a key to determine whether an ArrayList 
holding objects of that type is already present in the H ashM ap. If so, that 
ArrayList is extracted and the object is added to the ArrayList. If not, the 
Class object and a new ArrayList are added as a key- value pair. 

You can get an Iterator of al I the C lass objects from keys( ), and use each 
Class object to fetch the corresponding ArrayList with get( ). And that's 
all there is to it. 

Thefiller( ) method is interesting because it takes advantage of the 
design of ParseTrash.fi II Bin( ), which doesn't just try to fill an ArrayList 
but instead anything that impl ements the Fill able interface with its 
addTrash( ) method. All filler( ) needs to do isto return a reference to an 
interface that implements Fi liable, and then this reference can be used as 
an argument to fil I Bin( ) likethis: 

ParseTrash . f illBin ( "Trash. dat", bin . filler ( ) ) ; 



To produce this reference, an anonymous inner class (described in Chapter 
8 of Thinking in Java, 2 nd edition) is used. You never need a named class to 
implement Fill able, you just need a reference to an object of that class, 
thus this is an appropriate use of anonymous inner classes. 

An interesting thing about this design is that even though it wasn't 
created to hand I e the sorting, fill Bin( ) is performing a sort every time it 
i nserts a T rash object i nto bi n . 

Much of class DynaT rash should be familiar from the previous 
examples. Thistime, instead of placing the new Trash objects into a bin 
of type Array Li st, the bin is of typeTypeM ap, so when the trash is 
thrown into bin it's immediately sorted byTypeM ap's internal sorting 
mechanism. Stepping through theTypeM ap and operating on each 
i nd i vi d u al A rray L i st becomes a si mpl e matter: 

Iterator keys = bin. keys (); 
while (keys . hasNext ( ) ) 
Trash. sumValue ( 

bin . get ( (Class ) keys . next ( ) ) iterator ( ) ) ; 

As you can see, adding a new type to thesystem won't affect thiscodeat 
al I , nor the cod einTypeMap.Thisis certai n I y the smal I est sol uti on to the 
problem, and arguably the most elegant as well. It does rely heavily on 
RTTI, but notice that each key-value pair in the Hash Map islookingfor 
only one type. In addition, there's no way you can "forget" to add the 
proper code to this system when you add a new type, si nee there isn't 
any code you need to add. 

Summary 

Coming up with a design such asTrashVisitor.java that contains a larger 
amount of code than the earl i er desi gns can seem at f i rst to be 
counterproductive. It pays to noticewhat you're trying to accomplish 
with various designs. Design patterns in general strive to separate the 
thi n gs that chan ge from the th i n gs that stay the same. The "thi ngs that 
change" can refer to many different kinds of changes. Perhaps the change 
occurs because the program is placed into a new environment or because 
something in the current environment changes (this could be: "The user 



wants to add a new shape to the diagram currently on thescreen"). Or, as 
in thiscase, the change could be the evolution of the code body. While 
previous versions of the trash sorting example emphasized the addition 
of new types of Trash to the system, TrashVisitor.java allows you to 
easily add new functionality without disturbing theTrash hierarchy. 
There's more codein TrashVisitor.java, but adding new functionality to 
Visitor is cheap. If this is something that happens a lot, then it's worth 
the extra effort and code to make it happen more easily. 

The discovery of the vector of change is no trivial matter; it's not 
something that an analyst can usually detect before the program sees its 
initial design. The necessary information will probably not appear until 
later phases in the project: sometimes only at the design or 
implementation phases do you discover a deeper or more subtle need in 
yoursystem. In the case of adding new types (which was the focus of 
most of the "recycle" examples) you might realize that you need a 
particular inheritance hierarchy only when you are in the maintenance 
phase and you begin extending the system! 

One of the most important things that you'll learn by studying design 
patterns seems to be an about-face from what has been promoted so far 
in this book. That is: "OOP isall about polymorphism." This statement 
can produce the "two-year-old with a hammer" syndrome (everything 
looks I ike a nail). Put another way, it's hard enough to "get" 
polymorphism, and once you do, you try to cast all your designs into that 
one particular mold. 

What design patterns say is that OOP isn't just about polymorphism. It's 
about "separati ng the thi ngs that change from the thi ngs that stay the 
same." Polymorphism is an especially important way to do this, and it 
turns out to be helpful if the programming language directly supports 
polymorphism (so you don't have to wire it in yourself, which would 
tend to make it prohibitively expensive). But design patterns in general 
show other ways to accomplish the basic goal, and once your eyes have 
been opened to thi s you will begi n to search for more creati ve desi gns. 

Si nee the Design Patterns book came out and madesuch an impact, 
people have been searching for other patterns. You can expect to see 
more of these appear as ti me goes on. H ere are some sites recommended 
by Jim Coplien, of C++ fame (http://www.bdl-labs.com/~cope), who is one 
of the mai n proponents of the patterns movement: 



http://st-www.cs.uiuc.edu/users/patterns 

http://c2.com/cgi/wiki 

http://c2.com/ppr 

http://www.bell-labs.com/people/cope/Patterns/Process/index.html 

http://www.bell-labs.com/cgi-user/OrgPatterns/OrgPatterns 

http://st-www.cs.uiuc.edu/cgi-bin/wikic/wikic 

http://www.cs.wustl.edu/~schmidt/patterns.html 

http://www.espinc.com/patterns/overview.html 

Also note there has been ayearly conference on design patterns, called 
PLOP, that produces a published proceedings, thethird of which came 
out in late 1997 (all published by Addison-Wesley). 

Exercises 

1. Add a class Plastic to TrashVisitor.java. 

2. Add a class Plastic to DynaTrash.java. 

3. Createa decorator NkeVisitableDecorator, but for the multiple 
dispatching example, along with an "adapter decorator" class like 
the one created for VisitableDecorator. Build the rest of the 
example and show that it works. 



13: Projects 



A number of more challenging projects for you to solve. 
[[Some of these may turn into examples in the book, and 
so at some point might disappear from here]] 

Rats & Mazes 

First, create a Blackboard (cite reference) which isan object on which 
anyone may record information. This particular blackboard draws a 
maze, and is used as information comes back about the structure of a 
maze from the rats that are i nvesti gati ng it. 

N ow create the maze itself . Li ke a real maze, this object reveals very I ittl e 
information about itself — given a coordinate, it will tell you whether 
there are wal I s or spaces i n the four d i recti ons i mmed i atel y su rrou nd i ng 
that coordinate, but no more. For starters, read the maze in from a text 
file but consider hunting on the i nternet for a maze-generating algorithm. 
In any event, the result should bean object that, given a maze coordinate, 
will report walls and spaces around that coordinate. Also, you must be 
abl e to ask it for an entry poi nt to the maze. 

Finally, create the maze-investigating Rat class. Each rat can 
communicate with both the blackboard to give the current information 
and the maze to request new information based on the current position of 
the rat. H owever, each time a rat reaches a decision point where the maze 
branches, it creates a new rat to go down each of the branches. Each rat is 
driven by its own thread. When a rat reaches a dead end, it terminates 
itself after reporting the results of its final investigation to the blackboard. 

The goal isto completely map the maze, but you must also determine 
whether the end condition will be naturally found or whether the 
blackboard must be responsible for the decision. 

A n exampl e i mpl ementati on by J eremy M eyer: 

■ //: cl3 :Maze . java 



import java . util . * ; 
import java.io.*; 
import java.awt.*; 



public class Maze extends Canvas { 

private Vector lines; // a line is a char array 
private int width = -1; 
private int height = -1; 

public static void main (String [] args) 
throws IOException { 

if (args. length < 1) { 

System. out .println ( "Enter filename" ) ; 

System . exit ( ) ; 

} 

Maze m = new Maze () ; 

m. load (args [ ] ) ; 

Frame f = new Frame ( ) ; 

f . set Size (m. width*20, m.height*20) ; 

f . add (m) ; 

Rat r = new Rat (m, 0, 0); 
f . setVisible (true) ; 

} 

public Maze ( ) { 

lines = new Vector (); 
setBackground (Color . light Gray) ; 

} 

synchronized public boolean 
isEmptyXY ( int x, int y) { 

if (x < 0) x += width; 

if (y < 0) y += height; 

// Use mod arithmetic to bring rat in line: 
byte [ ] by = 

(byte [ ] ) (lines . elementAt (y%height ) ) ; 
return by [ x%width] == ' '; 

} 

synchronized public void 

setXY(int x, int y, byte newByte) { 

if (x < 0) x += width; 

if (y < 0) y += height; 

byte [ ] by = 

(byte [ ] ) (lines . elementAt (y%height ) ) ; 

by[x%width] = newByte; 

repaint ( ) ; 



public void 

load (String filename) throws IOException { 
String currentLine = null; 
Buf f eredReader br = new Buf f eredReader ( 

new FileReader (filename) ) ; 
for ( currentLine = br . readLine () ; 
currentLine != null; 
currentLine = br . readLine () ) { 
lines . addElement (currentLine . getBytes () ) ; 
if (width < | | 

currentLine . getBytes ( ) .length > width) 
width = currentLine . getBytes (). length; 

} 

height = lines . size () ; 
br . close ( ) ; 

} 

public void update (Graphics g) { paint (g) ; } 
public void paint (Graphics g) { 

int canvasHeight = this . getBounds ( ) .height; 
int canvasWidth = this . getBounds ( ) .width; 
if (height < 1 | | width < 1) 

return; // nothing to do 
int width = 

( (byte [ ] ) (lines . elementAt (0 ) ) ) . length; 
for (int y = 0; y < lines . size () ; y++) { 
byte [ ] b; 

b = (byte[]) ( lines . elementAt (y) ) ; 
for (int x = 0; x < width; x++) { 
switch (b [x] ) { 

case ' ' : // empty part of maze 
g.setColor(Color. light Gray ) ; 
g. f illRect ( 

x* (canvasWidth/width) , 
y* (canvasHeight/height) , 
canvas Width /width, 
canvasHeight/height ) ; 
break; 

case ' * ' : //a wall 

g. set Color (Color. darkGray) ; 
g. f illRect ( 

x* (canvasWidth/width) , 
y* (canvasHeight/height) , 
(canvasWidth/width) -1, 
(canvasHeight/height) -1) ; 



break; 

default: // must be rat 

g.setColor(Color.red) ; 
g. f illOval (x* (canvasWidth/width) , 
y* (canvasHeight/height) , 
canvas Width/ width, 
canvasHeight/height ) ; 
break; 

} 

} 

} 

} 

} ///:- 



// : cl3 : Rat . java 

public class Rat { 

static int ratCount = 0; 
private Maze prison; 
private int vertDir = 0; 
private int horizDir = 0; 
private int x, y; 
private int myRatNo = 0; 

public Rat (Maze maze, int xStart, int yStart) { 
myRatNo = ratCount++; 

System . out . println ( "Rat no." + myRatNo + 

" ready to scurry."); 
prison = maze; 
x = xStart; 
y = yStart; 

prison . setXY (x, y, (byte)'R'); 
new Thread () { 

public void run ( ) { scurry () ; } 
} . start ( ) ; 

} 

public void scurry () { 

// Try and maintain direction if possible. 
// Horizontal backward 
boolean ratCanMove = true; 
while ( ratCanMove ) { 

ratCanMove = false; 

// South 

if (prison . isEmptyXY (x, y + 1)) { 
vertDir = 1; horizDir = 0; 



ratCanMove = true; 

} 

// North 

if (prison . isEmptyXY (x, y - 1)) 

if (ratCanMove) 

new Rat (prison, x, y-1) ; 

// Rat can move already, so give 

// this choice to the next rat. 

else { 

vertDir = -1; horizDir = 0; 
ratCanMove = true; 

} 

// West 

if (prison . isEmptyXY (x-1, y) ) 

if (ratCanMove) 

new Rat (prison, x-1, y) ; 

// Rat can move already, so give 

// this choice to the next rat. 

else { 

vertDir = 0; horizDir = -1; 
ratCanMove = true; 

} 

// East 

if (prison . isEmptyXY (x + 1 , y) ) 

if (ratCanMove) 

new Rat (prison, x+1, y) ; 

// Rat can move already, so give 

// this choice to the next rat. 

else { 

vertDir = 0; horizDir = 1; 
ratCanMove = true; 

} 

if (ratCanMove) { // Move original rat. 
x += horizDir; 
y += vertDir; 

prison . set XY (x, y, (byte) ' R ' ) ; 
} // If not then the rat will die. 
try { 

Thread. sleep (2000) ; 
} catch ( InterruptedException ie) {} 

} 

System . out . println ( "Rat no." + myRatNo + 
" can't move .. dying .. aarrgggh .") ; 



} ///:- 



The maze initialization file: 

//:! cl3 : Amaze . txt 

-k ~k ~k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k -k ~k ~k 

-k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k -k-k-k-k-k-k-k-k-k-k -k -k 'k ~k ~k 

-k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k ~k 

-k ~k ~k ~k ~k ~k ~k ~k ~k ~k 

///:- 



Other maze resources 

A discussion of algorithms to create mazes as well asjava source codeto 
implement them: 

Ihttp:/ / www.mazeworks.com/ mazeqen/ mazeqeahtm 

A discussion of algorithms for collision detection and other 
individual/ group moving behavior for autonomous physical objects: 

http:/ / www.red3d.com/ cwr/ steer/ 



XML Decorator 



Create a pai r of decorators for 1/ O Readers and Writers that encode (for 
the Writer decorator) and decode (for the reader decorator) XM L. 



